bitmasking plug-in for the opc da...

Bitmask Plug-Infor the PI Interface for OPC DA

Version 2.4.4.x

OSIsoft, LLC777 Davis St., Suite 250San Leandro, CA 94577 USATel: (01) 510-297-5800Fax: (01) 510-357-8136Web: http://www.osisoft.com

OSIsoft Australia • Perth, AustraliaOSIsoft Europe GmbH • Frankfurt, GermanyOSIsoft Asia Pte Ltd. • SingaporeOSIsoft Canada ULC • Montreal & Calgary, CanadaOSIsoft, LLC Representative Office • Shanghai, People’s Republic of ChinaOSIsoft Japan KK • Tokyo, JapanOSIsoft Mexico S. De R.L. De C.V. • Mexico City, MexicoOSIsoft do Brasil Sistemas Ltda. • Sao Paulo, Brazil

Copyright: © 2023 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, Sigmafine, Analysis Framework, 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 RIGHTSUse, 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: 04/2013

http://www.osisoft.com/

Table of Contents

Terminology......................................................................................................................v

Chapter 1. Introduction...................................................................................................1Reference Manuals............................................................................................1Supported Features...........................................................................................1

Chapter 2. Principles of Operation................................................................................5Limits.................................................................................................................. 5

Chapter 3. Installation Checklist....................................................................................7Data Collection Steps.........................................................................................7

Chapter 4. Interface and Plug-In Installation and Administration..............................9Naming Conventions and Requirements............................................................9Interface Directories.........................................................................................10

PIHOME Directory Tree.........................................................................10Interface Installation Directory...............................................................10Plug-Ins Directory..................................................................................10

Interface Installation Procedure.......................................................................11Installing the Plug-In Separately......................................................................11Upgrading the Plug-In......................................................................................11Moving the Plug-In to a New Directory.............................................................11Uninstalling the Plug-In....................................................................................12

Chapter 5. Digital States...............................................................................................13

Chapter 6. PI Point Configuration................................................................................15Point Attributes.................................................................................................15

Tag........................................................................................................15PointSource...........................................................................................15PointType...............................................................................................16Location1...............................................................................................16Location2...............................................................................................16Location3...............................................................................................16Location4...............................................................................................16Location5...............................................................................................17InstrumentTag........................................................................................17ExDesc for Bitmask PI Tags..................................................................18Format – Priorty Bits..............................................................................19Scan......................................................................................................23Shutdown...............................................................................................23

Output Points...................................................................................................24

Chapter 7. Startup Command File...............................................................................25Configuring the Interface with PI ICU...............................................................25

OPCInt Interface Page...........................................................................25Bitmasking Plug-In for the OPC DA Interface iii

Command-line Parameters..............................................................................27

Chapter 8. Interface Node Clock..................................................................................29

Chapter 9. Starting / Stopping the Interface...............................................................31Starting Interface as a Service.........................................................................31Stopping Interface Running as a Service.........................................................31

Chapter 10. Error and Informational Messages........................................................33Message Logs..................................................................................................33Troubleshooting...............................................................................................33System Errors and PI Errors............................................................................34

Chapter 11. Revision History.....................................................................................35

Bitmasking Plug-In for the OPC DA Interface iv

Terminology

To understand this interface manual, you should be familiar with the terminology used in this document.

BufferingBuffering refers to an Interface Node’s ability to store temporarily the data that interfaces collect and to forward these data to the appropriate PI Servers.

N-Way BufferingIf you have PI Servers that are part of a PI Collective, PIBufss supports n-way buffering. N-way buffering refers to the ability of a buffering application to send the same data to each of the PI Servers in a PI Collective. (Bufserv also supports n-way buffering to multiple PI Server however it does not guarantee identical archive records since point compressions specs could be different between PI Servers. With this in mind, OSIsoft recommends that you run PIBufss instead.)

ICUICU refers to the PI Interface Configuration Utility. The ICU is the primary application that you use 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, OSIsoft discourages this approach. Instead, OSIsoft strongly recommends that you use the ICU for interface management tasks.

ICU ControlAn ICU Control is a plug-in to the ICU. Whereas the ICU handles functionality common to all interfaces, an ICU Control implements interface-specific behavior. Most PI interfaces have an associated ICU Control.

Interface NodeAn Interface Node is a computer on which

the PI API and/or PI SDK are installed, and

PI Server programs are not installed.

PI APIThe PI API is a library of functions that allow applications to communicate and exchange data with the PI Server. All PI interfaces use the PI API.

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

Bitmasking Plug-In for the OPC DA Interface v

PIHOMEPIHOME refers to the directory that is the common location for PI 32-bit client applications.

On a 32-bit operating system

A typical PIHOME is C:\Program Files\PIPC.

On a 64-bit operating system

A typical PIHOME is C:\Program Files (x86)\PIPC.

PI interfaces reside in a subdirectory of the Interfaces directory under PIHOME.

For example, files for the Modbus Ethernet Interface are in

[PIHOME]\Interfaces\ModbusE.

This document uses [PIHOME] as an abbreviation for the complete PIHOME or PIHOME64 directory. For example, ICU files in [PIHOME]\ICU.

PIHOME64PIHOME64 will be found only on a 64-bit operating system and refers to the directory that is the common location for PI 64-bit client applications.

A typical PIHOME64 is C:\Program File\PIPC.

PI interfaces reside in a subdirectory of the Interfaces directory under PIHOME64.

For example, files for a 64-bit Modbus Ethernet Interface would be found in

C:\Program Files\PIPC\Interfaces\ModbusE.

This document uses [PIHOME] as an abbreviation for the complete PIHOME or PIHOME64 directory. For example, ICU files in [PIHOME]\ICU.

PI SDKThe PI SDK is a library of functions that allow applications to communicate and exchange data with the PI Server. Some PI interfaces, in addition to using the PI API, require the use of the PI SDK.

PI Server NodeA PI Server Node is a computer on which PI Server programs are installed. The PI Server runs on the PI Server Node.

PI SMTPI SMT refers to PI System Management Tools. PI SMT is the program that you use for configuring PI Servers. A single copy of PI SMT manages multiple PI Servers. PI SMT runs on either a PI Server Node or a PI Interface Node.

Pipc.logThe pipc.log file is 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 allows easy access to the pipc.log.

Bitmasking Plug-In for the OPC DA Interface vi

PointThe PI point is 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 foreign device. For example, a single “point” on the foreign device 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.

ServiceA Service is a Windows program that runs without user interaction. A Service continues to run after you have logged off from Windows. It has the ability to start up when the computer itself starts up.

The ICU allows you to configure a PI interface to run as a Service.

Tag (Input Tag and Output Tag)The tag attribute of a PI point is 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.

Interfaces read values from a device and write these values to an Input Tag. Interfaces use an Output Tag to write a value to the device.

Bitmasking Plug-In for the OPC DA Interface vii

Chapter 1. Introduction

The PI Interface for OPC DA (OPCInt) is generic in that it does not interpret words that it retrieves from an OPC server. Sometimes the words are packed with multiple values such that each bit or group of bits are a distinct value. The BitMask Plug-in for the PI Interface for OPC DA was written by OSIsoft in order to get complete information from the bits (through PI OPC). The OPCPlugInBitMask.DLL allows for selecting specific bits out of a data word received from an OPC server and stores that value in a PI tag.

Note: Neither this manual nor the plug-in are stand-alone products; they are to be used in conjunction with the PI Interface for OPC DA. This version of the plug-in requires 2.4.4.0 or above of the PI Interface for OPC DA.

Reference Manuals

OSIsoft PI Interface for OPC DA

PI Server manuals

PI API Installation Instructions

UniInt Interface User Manual

Supported Features

Feature Support

Part Number PI-IN-OS-OPC-NTI

* 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


Windows Vista

32-bit OS Yes No


Windows 2008 Server

32-bit OS Yes No


Windows 2008 R2 Server

Bitmasking Plug-In for the OPC DA Interface 1

Feature Support


Windows 7

32-bit OS Yes No


* APS Connector See note below

Point Builder Utility No

ICU Control Yes

PI Point Types Same as OPCInt: int16, int32, digital, float16, float32, float64, string

Sub-second Timestamps Yes

Sub-second Scan Classes See PI Interface for PI Interface for OPC DA

Automatically Incorporates PI Point Attribute Changes

Yes

Exception Reporting Unconditional. See ExcDev, ExcDevPercent, ExcMin, and ExcMax.

Outputs from PI No

Inputs to PI: Scan-based / Unsolicited / Event Tags

Same as OPCInt

Supports Questionable Bit No

Supports Multi-character PointSource See PI Interface for OPC DA

Maximum Point Count Unlimited

* Uses PI SDK No

PINet String Support N/A

* Source of Timestamps Interface/OPC Server

History Recovery No

UniInt-based* Disconnected Startup* SetDeviceStatus

YesSee PI Interface for OPC DASee PI Interface for OPC DAPI Interface for OPC DA

Failover See PI Interface for OPC DA

Vendor Software Required on Data Source

No

Vendor Hardware Required No

Additional PI Software Included with Interface

See PI Interface for OPC DA

* Device Point Types VT_I2, VT_UI2, and VT_I4

Serial-Based Interface No

* See available paragraphs below for further explanation.

PlatformsThe BitMask Plug-In is designed to run on the above mentioned Microsoft Windows operating systems and their associated service packs.


APS ConnectorThe Interface for OPC DA - APS Connector does not support plug-in specific points. That is, the APS Connector cannot create or edit PI points for the BitMask Plug-in.

Note: If PI APS is used with an instance of the Interface for OPC DA that uses the BitMask Plug-in, change the master synchronization setting to off (disabled) for all PI points that are configured for the BitMask Plug-in.

Uses PI SDKThe PI SDK and the PI API are bundled together and must be installed on each PI Interface Node. The BitMask Plug-in does not specifically make PI SDK calls.

Source of TimestampsThe interface can accept timestamps from the OPC Server or it can provide timestamps from the local node. This is controlled by a command-line parameter.

UniInt-basedUniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by developers and is integrated into many interfaces, including the Interface for OPC DA . 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 UniInt-supplied 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.

Device Point TypesThe result may be stored in a Digital or Integer PI tag. Input datatypes supported are VT_I2, VT_UI2, and VT_I4. If sent to a Digital tag, Location2=3 is required. (See PI Interface OPC DA manual)


Chapter 2. Principles of Operation

The PI Interface for OPC DA connects OPC variables (which are defined by OPC symbols for the specific device) to a PI tag. The OPC symbol for any PI tag is saved in that tag’s ‘InstrumentTag’ attribute or ‘ExDesc’ (Extended Descriptor) (See the PI Interface for OPC DA manual for exact tag configuration details.) To use the bit-masking capability, the PI tag must indicate the bit mask in the Extended Descriptor.

Limits

PI Interface for OPC DA Version 2.4.4.0 or greater is required.

The result may be stored in a Digital or Integer PI tag. Input datatypes supported are VT_I2, VT_UI2, and VT_I4. If sent to a Digital tag, Location2=3 is required. (See PI Interface for OPC DA manual)

A Digital Tag must use a Digital State Set with a sufficient number of states.2n Digital States are required, with n being the number of set bits in the bit mask.

Outputs are not supported by the plug-in.

For an output tag (PI OPC server) the bit mask is ignored.

The PI Value is sent to the OPC tag specified without any processing by the plug-in.

Bits from different data words cannot be combined on the OPC server.

Data arrays (OPC Items that are array type) are not supported.


Chapter 3. Installation Checklist

If you are familiar with running PI data collection interface programs, this checklist helps you get the Interface for OPC DA running with the BitMask Plug-in. If you are not familiar with PI interfaces, return to this section after reading both the PI Interface for PI Interface for OPCDAuser manual and the rest of this manual in detail.

This checklist is taken from the PI Interface for PI Interface for OPC DAuser manual and extended with details specific to the BitMask Plug-in. The detailed explanations of most steps in the following lists are not duplicated in this document. Refer to the PI Interface for PI Interface for OPC DAuser manual for the detailed explanations.

This checklist summarizes the steps for installing the Interface for OPC DA and the BitMaskPlug-in. You need not perform a given task if you have already done so as part of the installation of another interface. For example, you only have to configure one instance of Buffering for every Interface Node regardless of how many interfaces run on that node.

The Data Collection Steps below are required. Refer to the “Interface Diagnostics” and “Advanced Interface Features” sections in the PI Interface for PI Interface for OPC DAuser manual for information on configuring diagnostics and advanced features of the Interface for OPC DA .

Data Collection Steps

1. Confirm that you can use PI SMT to configure the PI Server. You need not run PI SMT on the same computer on which you run this Interface.

2. If you are running the Interface on an Interface Node, edit the PI Server’s security configuration to allow the Interface to write data.

3. Run the installation kit for PI Interface Configuration Utility (ICU) on the Interface Node if the ICU will be used to configure the Interface. The ICU installation kit runs the PI SDK installation kit, which installs both the PI API and the PI SDK.

4. Run the installation kit for this Interface. This kit also runs the PI SDK installation kit which installs or upgrades both the PI API and the PI SDK, if necessary.

5. If you are running the Interface on an Interface Node, check the computer’s time zone properties. An improper time zone configuration can cause the PI Server to reject the data that this Interface writes.

6. Run the ICU and configure a new instance of this Interface. Essential startup parameters for this Interface are:

Point Source (/PS=x)

Interface ID (/ID=#)

PI Server (/Host=host:port)

Scan Classes (/f=x)


OPC Server (/SERVER=node:name)

Post-processing DLL (/DLL=<UNC Path>)

7. Configure DCOM permissions. If the Interface for OPC DA and the OPC Server are on different nodes, configure DCOM settings for both nodes. Otherwise, check default DCOM permissions and make the OPC Server node use the defaults.

8. Use the OPCClient Tool to confirm connection between the Interface Node and the OPC Server.

9. If you will use digital points, define the appropriate digital state sets. For example, the PI points for the ComeGo event property can be digital points with a digital state set that contains “Go” as state 0 and “Come” as state 1.

10. Build input tags for this Interface. Important point attributes and their use are:

PointSource identifies all points that belong to this instance of the Interface.Location1 specifies the Interface instance ID.Location2 is used to indicate special handingLocation3 tag type (Polled/Advised/Output).Location4 specifies the scan class.Location5 set to 0 for BitMask Plug-in points. InstrumentTag specifies the ItemID for the OPC Server item.ExDesc uses one of three keywords to designates the bitmask - Bitmask, PRI_BIT or PRI_BITZ

11. Start the Interface interactively and confirm its successful connection to the PI Server without buffering.

12. Confirm that the Interface collects data successfully.

13. Stop the Interface and configure a buffering application (either Bufserv or PIBufss). When configuring buffering, use the ICU menu item Tools Buffering… Buffering Settings to make a change to the default value (32678) for the Primary and Secondary Memory Buffer Size (Bytes) to 2000000. This will optimize the throughput for buffering and is recommended by OSIsoft.

14. Start the buffering application and the Interface. Confirm that the Interface works together with the buffering application by either physically removing the connection between the Interface Node and the PI Server Node or by stopping the PI Server.

15. Configure the Interface to run as a Service. For COM/DCOM security, the service may not be able to run as LocalSystem. Confirm that the Interface runs properly as a Service.

16. Restart the Interface Node and confirm that the Interface and the buffering application restart.


Chapter 4. Interface and Plug-In Installation

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

After the Interface has been installed and tested, Buffering should be enabled on the PI Interface Node. Buffering refers to either PI API Buffer Server (Bufserv) or the PI Buffer Subsystem (PIBufss). For more information about Buffering see the “Buffering” chapter in the PI Interface for PI Interface for OPC DA user manual.

In most cases, interfaces on PI Interface Nodes should be installed as automatic services. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of a power failure.

The guidelines are different if an interface is installed on the PI Server Node. In this case, the typical procedure is to install the PI Server as an automatic service and install the Interface as an automatic service that depends on the PI Update Manager and PI Network Manager services. This typical scenario assumes that Buffering is not enabled on the PI Server Node. Bufserv can be enabled on the PI Server Node so that interfaces on the PI Server Node do not need to be started and stopped in conjunction with PI, but it is not standard practice to enable buffering on the PI Server Node. The PI Buffer Subsystem can also be installed on the PI Server. See the UniInt Interface User Manual for special procedural information.

Naming Conventions and Requirements

In the installation procedure below, it is assumed that the name of the interface executable is OPCInt.exe and that the startup command file is called OPCInt.bat.

When Configuring the Interface ManuallyIt is customary for the user to rename the executable and the startup command file when multiple copies of the interface are run. For example, OPCInt1.exe and OPCInt1.bat would typically be used for interface number 1, OPCInt2.exe and OPCInt2.bat for interface number 2, and so on. When an interface is run as a service, the executable and the command file must have the same root name because the service looks for its command-line parameters in a file that has the same root name.


Interface Directories

PIHOME Directory Tree

32-bit InterfacesThe [PIHOME] directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the %windir% directory.

For 32-bit operating systems a typical pipc.ini file contains the following lines:[PIPC]PIHOME=C:\Program Files\PIPC

For 64-bit operating systems a typical pipc.ini file contains the following lines:[PIPC]PIHOME=C:\Program Files (X86)\PIPC

The above lines define the root of the PIHOME directory tree on the C: drive. The PIHOME directory does not need to be on the C: drive. OSIsoft recommends using the paths shown above as the root PIHOME directory name.

Interface Installation Directory

The interface installation kit will automatically install the interface to:[PIHOME]\Interfaces\OPCInt\

PIHOME is defined in the pipc.ini file.

Plug-Ins Directory

Several plug-in DLLs are included with the Interface for OPC DA . Plug-in DLLs perform post-processing for input tags or pre-processing for output tags for specific applications or OPC Servers.

The interface installation kit installs plug-in DLLs in:[PIHOME]\Interfaces\OPCInt\Plug-Ins

The documentation for plug-in DLLs is installed in:[PIHOME]\Interfaces\OPCInt\Plug-Ins\Documentation


Interface Installation Procedure

The Interface for OPC DA setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000 and later operating systems. To install, run the OPCInt_#.#.#.#.exe installation kit.

Installing the Plug-In Separately

The BitMask Plug-in and its documentation can be downloaded separately from the Interface for OPC DA . The standalone installation file is a self-extracting zip file that creates the plug-in files directly on the target Interface Node. Unlike most OSIsoft installation kits, the self-extracting zip file for this plug-in does not contain a Windows Installer file.

To install the BitMask Plug-in from the standalone installation file:

1. Download the standalone installation file to the [PIHOME]\Interfaces\OPCInt folder on the Interface Node.

2. Run the installation file, which opens the WinZip Self-Extractor – OPCPluginBitmask dialog box.

3. Click Unzip.

4. Click OK on the dialog box that opens.

5. Click Close.

6. The plug-in DLL is extracted to [PIHOME]\Interfaces\OPCInt\Plug-Ins (the folder for plug-ins installed by the Interface for OPC DA installation kit). The release notes and a copy of this manual are extracted to [PIHOME]\Interfaces\OPCInt\Plug-Ins\Documentation.

Upgrading the Plug-In

If the plug-in is upgraded independent of the Interface for OPC DA , install the plug-in the appropriate directory. To determine the path that the interface uses to load the plug-in, run PI ICU, select the interface instance, select the OPCInt ICU Control, select Plug-Ins, and find the path in the Post Processing DLL box. Alternatively, open the batch file and find the path in the /DLL= command-line parameter. Then, stop and restart the Interface for OPC DA according to the instructions in the Starting / Stopping the Interface chapter.

Moving the Plug-In to a New Directory

Although it is not recommended, it is possible to move the plug-in to a new directory. OPCInt.bat must be updated to reflect the name of the new directory, which is easily done using the browse button on the Plug-Ins ICU tab. The interface must then be restarted as described in the PI Interface for OPC DA manual.


Interface and Plug-In Installation

Uninstalling the Plug-In

To run the interface without the plug-in, run the PI ICU and remove the entry in the Post Processing DLL text box. Alternatively, edit the batch file and delete the /DLL= command-line parameter. Then, stop and restart the Interface for OPC DA according to the instructions in the Starting / Stopping the Interface chapter.

A point configuration ExDesc parameter bitbask=0xnnn is ignored without the /DLL command-line parameter.

Alternatively, points without bitmask= in ExDesc are handled the standard way, so the /DLL= command-line parameter might not need to be removed.

12

Chapter 5. Digital States

For more information regarding Digital States, refer to the PI Server documentation.

Digital State SetsPI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. For more information about PI digital points and editing digital state sets, see the PI Server manuals.

An interface point that contains discrete data can be stored in PI as a digital point. A digital point associates discrete data with a digital state set, as specified by the user.

System Digital State SetSimilar to digital state sets is the system digital state set. This set is used for all points, regardless of type, to indicate the state of a point at a particular time. For example, if the interface receives bad data from the data source, it writes the system digital state Bad Input to PI instead of a value. The system digital state set has many unused states that can be used by the Interface and other PI clients. Digital States 193-320 are reserved for OSIsoft applications.


Chapter 6. PI Point Configuration

The PI point is the basic building block for controlling data flow to and from the PI Server. A single point is configured for each measurement value that needs to be archived.

Point Attributes

Use the point attributes below to define the PI point configuration for the Interface, including specifically what data to transfer.

Tag

The Tag attribute (or tagname) is the name for a point. There is a one-to-one correspondence between the name of a point and the point itself. Because of this relationship, PI documentation uses the terms “tag” and “point” interchangeably.

Follow these rules for naming PI points:

The name must be unique on the PI Server.

The first character must be alphanumeric, the underscore (_), or the percent sign (%).

Control characters such as linefeeds or tabs are illegal.

The following characters also are illegal: * ' ? ; { } [ ] | \ ` ‘ "

LengthDepending on the version of the PI API and the PI Server, this Interface supports tags whose length is at most 255 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Server versions.

PI API PI Server Maximum Length

1.6.0.2 or higher 3.4.370.x or higher 1023

1.6.0.2 or higher Below 3.4.370.x 255

Below 1.6.0.2 3.4.370.x or higher 255

Below 1.6.0.2 Below 3.4.370.x 255

If the PI Server version is earlier than 3.4.370.x or the PI API version is earlier than 1.6.0.2, and you want to use a maximum tag length of 1023, you need to enable the PI SDK. See the PI Interface for PI Interface for OPC DA manual.

PointSource

The PointSource attribute contains a unique, single or multi-character string that is used to identify the PI point as a point that belongs to a particular interface. For additional information, see the /ps command-line parameter and the “PointSource” section in the PI Interface for PI Interface for OPC DA manual.


PointType

Typically, device point types do not need to correspond to PI point types. For example, integer values from a device can be sent to floating-point or digital PI tags. Similarly, a floating-point value from the device can be sent to integer or digital PI tags, although the values will be truncated.

Float16, float32, float64, int16, int32, and digital point types are supported for PI points that are configured for the BitMask Plug-in. For more information on the individual PointTypes, see PI Server manuals.

Location1

Location1 indicates to which copy of the Interface the point belongs. The value of this attribute must match the /id startup parameter.

Location2

The Interface for OPC DA uses Location2 to indicate several forms of special handling.

Location3

Location3 indicates the method that the Interface should use to read the OPC item. For BitMask Plug-in points, Location3 can be 0 (Polled or Event triggered) or 1 (Advised).

Location4

Location4 defines the scan class for the PI point. The updates from the OPC Server come in groups: at start-up, the Interface for OPC DA creates a group on the OPC Server for each scan class and adds all points assigned to the scan class to the group. Up to 200 groups, and thus 200 scan classes, can be defined. The OPC Server is queried for all points within a group at the same time; therefore some consideration should be given to the number of OPC Items in each scan class. Having more than one scan class with the same scan period is allowed, and using different offsets on those scan classes may help performance. However, the OPC Server is in control of when to read the data source to update its data cache, and specifying offsets may have no effect on when the data is actually read by the OPC Server.

Note: By convention, the first scan class is reserved for Advise points. Any points which are not advised and use the first scan class (Location4 = 1) will not be polled.

Scan-based (Polled) InputsLocation4 specifies the scan class for the PI point. The /f interface parameter corresponding to the scan class determines the frequency at which input points are scanned for new values. For more information, see the description of the /f parameter in the “Startup Command File” chapter of the PI Interface for PI Interface for OPC DA manual.

Advise PointsLocation4 specifies the scan class for the PI point. The /f interface parameter corresponding to the scan class specifies the Requested Update Rate for the group: the OPC Server agrees to


check for new values at least this often, which allows the use of a larger value for points which don’t change often to lighten the load on the OPC Server. For more information, see the description of the /f parameter in the “Startup Command File” chapter of the PI Interface for PI Interface for OPC DA manual.

Trigger-based Inputs and Output PointsLocation 4 should be set to zero for these points.

Location5

Location5 is used for Advise tags to define a Deadband value which will be used by the OPC Server. Deadband processing only applies to analog values in the OPC Server. Therefore, set Location5 to 0 for BitMask Plug-in points.

InstrumentTag

This field contains the ItemID for the tag. The format of this field depends on the specific OPC Server being used. Refer to the documentation for the server to determine the proper format. This field must exactly match the point defined on the OPC Server. That means punctuation, spaces, uppercase vs. lowercase, etc. If the ItemID is longer than 32 characters and you have a PI 2 system, use the ExDesc attribute and leave this attribute blank.

Note: If the ItemID contains trailing spaces, and the interface is configured to NOT use the PISDK, you must specify the ItemID in the ExDesc field instead, as trailing spaces will be truncated by the API when the PISDK is not used.

LengthDepending on the version of the PI API and the PI Server, this Interface supports an InstrumentTag attribute whose length is at most 32 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Server versions.


1.6 or higher 3.4.370.x or higher 1023

1.6 or higher Below 3.4.370.x 32

Below 1.6 3.4.370.x or higher 32

Below 1.6 Below 3.4.370.x 32

If the PI Server version is earlier than 3.4.370.x or the PI API version is earlier than 1.6.0.2, and you want to use a maximum InstrumentTag length of 1023, you need to enable the PI SDK. See Appendix B: PI SDK Options for information.

To verify an ItemID, use the PI OPCClient. If the OPC server supports browsing, use List Server’s Tags to see a list of defined ItemIDs. Double-clicking on an ItemID in the tree will result in the full ItemID being displayed in the Item field. This is the ItemID that should be used in InstrumentTag.


PI Point Configuration

Note: If there is anything in the InstrumentTag, the ExDesc is not checked for an OPC ItemID.

ExDesc for Bitmask PI Tags

The OPCPlugInBitMask.DLL uses the keyword Bitmask, PRI_BIT or PRI_BITZ in the ExDesc point attribute to determine the masking. Bits cannot be combined from different data words on the OPC server. Data arrays are not supported.

Format - BITMASKBitmask=n

n may be a decimal, hexadecimal (0xnnnn) or binary (0bnnnnnnnnnnnnnnnn) number.

If combined with other keywords in exdesc (see PI Interface for OPC DA manual), they have to be separated by commas.

Keywords may appear in any order. Example:Event=pi-event.tag , Instr=OPCTag.xyz.name, Bitmask=0x0040

Keyword and number are case insensitive.

Example: BITMASK= 0Xaaaa

Leading zeros may be omitted. Spaces are allowed (but no space within numbers).

Decimal Bit MaskA decimal number is assumed (1, 2, 4, 8, ... etc to indicate single bits.)

Example: Bitmask = 3 (mask the last two bits) OPC Value (VT_I2) = 68 (= 64 + 4) Result = 0

Hexadecimal Bit MaskIf bitmask= is followed by 0x, the rest is interpreted as a hexadecimal number.

Example: Bitmask = 0x16OPC Value (VT_I2) = 68 = 0x44Result 0x02 = 2

Binary Bit MaskIf bitmask= is followed by 0b, the rest is interpreted as a bit pattern. The only valid characters are 0 or 1.

Example: Bitmask = 0b0100000000000111OPC Value (VT_I2) = 17476 = 0b0100010001000100Result 0b 1 100 = 0x0C = 12

Several bits in Bitmask may be set. They will be pushed together.

18

Format – Priorty Bits

Pri_bit=n or Pri_bitz=n

List up to 32 bits of the data quality, formatting all bit positions to two places and using 0-based notation (e.g., 00, 01, 03…32).

Prioritize the bit positions. The priority will indicate the order in which the plug-in examines the bit states. The order listed must match the ordering of the associated PI digital state set.

Optionally, a placeholder “??” can be used to indicate that the plug-in should ignore the corresponding digital state.

The following are explicit examples.

Example 1Assume the meanings of the bit positions of the data are as follows, where bit numbering uses traditional zero-based indexing:

Bit Position (0-based) Meaning, if set

0 Uninitialized

1 Stale

2 Bad

3 Reserved

4 Unreasonable

5 Commanded

6 Remote suspect

7 Remote replaced

8 Manual replaced

9 Reserved

10 Not in service

11 Tfail

12 Genrep

13 Testmode

14 Delayed

15 Unacknowledged

16 Abnormal

17 Inhibit

18 Notag

19 Reserved

20 Reserved

21 Reserved

22 Reserved

23 Reserved

24 Reserved

25 Reserved

26 Scan pending

27 Garbage



28 Suspect

29 Replaced

30 Good

Assume a PI digital state set named PRIORITY_BITS that is configured to capture some of the bits. The order of the state strings could be as follows:

Offset from Start of Set State String Corresponding Data source Bit

0 Good 30

1 Old 1

2 Bad 2

3 Unreasonable 4

4 RemSusp 6

5 RemRepl 7

6 ManRepl 8

7 Delayed 14

8 Abnormal 16

9 Suspect 28

10 Replaced 29

11 Garbage 27

The order of the strings in the digital set is significant, since this must correspond to the priority in which the user wishes the data quality to be examined. The first bit that is set will be used as the value. In this example, bit 30 representing the Good bit must be examined first, then bit 1, etc. If bit 30 is set, then the value 0 is saved to PI and the data quality value is examined no further. The value 0 is correlated with the state string “Good.”

Note: If a “Good” bit exists, it makes sense that it would be given the highest priority since this will usually decrease time spent examining data quality bits.

If bit 30 is not set, then if bit 1 is set, the value 1 is saved to PI, which corresponds to state string “Old.” The algorithm proceeds in similar fashion through all bits.

If none of the specified bits is set then:

If pri_bit is used, then BAD INPUT will be saved to the PI tag.

If pri_bitz is used then the 0 state will be saved to the PI tag.

The configuration of PRI_BIT for this example would be as follows:

PRI_BIT=30010204060708141628

The formatting of the bit positions is 0-based and two digits per bit. The bits are ordered from most significant to least significant.

Configuration of PRI_BIT is actually a bit more complex than shown above. The meanings of the bit states may be specific to a particular site. In many cases, when one bit state is set, other related bit states are set simultaneously. For example, a BAD bit may be set if any of ABNORMAL, DELAYED, OLD, SUSPECT, or GARBAGE is set. Therefore, it would make little sense to place the BAD bit at a higher priority than the other more specific qualities. Thus, the value that is saved to the PI tag is dependent upon the user’s judgment of priorities.

20

Example 2Assume the meanings of the bit positions of the data are those described in Example 1 above. Also assume a PI digital state set named PRIORITY_BITS2 that is configured to capture some of the bits. The order of the state strings could be as follows:

Offset from Start of Set State String Corresponding Data source Bit

0 Normal

1 Good 30

2 Old 1

3 Bad 2

4 Unreasonable 4

5 RemSusp 6

6 RemRepl 7

7 ManRepl 8

8 Delayed 14

9 Abnormal 16

10 Suspect 28

11 Replaced 29

12 Garbage 27

Note that PRIORITY_BITS2 in this example is similar to PRIORITY_BITS in Example 1, with the exception of an additional digital state “Normal” which does not correspond to any of the Data source Bit positions. In this case a placeholder “??” can be used to indicate that the plugin should ignore that digital state.

The configuration of PRI_BIT for this example would be as follows:

PRI_BIT=??30010204060708141628

where bit 30 will be examined first, then bit 01, then bit 02, etc. The first bit that is set will be used as the value.

If none of the specified bits is set then:

If pri_bit is used, then BAD INPUT will be saved to the PI tag.

If pri_bitz is used then the 0 state will be saved to the PI tag.

Note that multiple placeholders “??” can be used and they can occur anywhere within the configuration string.



LengthDepending on the version of the PI API and the PI Server, this Interface supports an ExDesc attribute whose length is at most 80 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Server versions.


1.6.0.2 or higher 3.4.370.x or higher 1023

1.6.0.2 or higher Below 3.4.370.x 80

Below 1.6.0.2 3.4.370.x or higher 80

Below 1.6.0.2 Below 3.4.370.x 80

If the PI Server version is earlier than 3.4.370.x or the PI API version is earlier than 1.6.0.2, and you want to use a maximum ExDesc length of 1023, you need to enable the PI SDK. See the PI Interface for PI Interface for OPC DA manual for information.

Performance Points For UniInt-based interfaces, the extended descriptor is checked for the string “PERFORMANCE_POINT”. If this character string is found, UniInt treats this point as a performance point. See the “Scan Class Performance Points” section in the PI Interface for PIInterface for OPC DA manual.

Scan

By default, the Scan attribute has a value of 1, which means that scanning is turned on for the point. Setting the scan attribute to 0 turns scanning off. If the scan attribute is 0 when the Interface starts, a message is written to the pipc.log and the tag is not loaded by the Interface. There is one exception to the previous statement.

If any PI point is removed from the Interface while the Interface is running (including setting the scan attribute to 0), SCAN OFF will be written to the PI point regardless of the value of the Scan attribute. Two examples of actions that would remove a PI point from an interface are to change the point source or set the scan attribute to 0. If an interface specific attribute is changed that causes the tag to be rejected by the Interface, SCAN OFF will be written to the PI point.

Shutdown

The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Server manuals.

Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are independent of the SHUTDOWN events that are written by the Interface when the /stopstat=Shutdown command-line parameter is specified.

22

SHUTDOWN events can be disabled from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, the default behavior of the PI Shutdown Subsystem can be changed to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the \PI\dat\Shutdown.dat file, as discussed in PI Server manuals.

Bufserv and PIBufSSIt is undesirable to write shutdown events when buffering is being used. Bufserv and PIBufSS are utility programs that provide the capability to store and forward events to a PI Server, allowing continuous data collection when the Server is down for maintenance, upgrades, backups, and unexpected failures. That is, when PI is shutdown, Bufserv or PIBufSS will continue to collect data for the Interface, making it undesirable to write SHUTDOWN events to the PI points for this Interface. Disabling Shutdown is recommended when sending data to a Highly Available PI Server Collective. Refer to the Bufserv or PIBufSS manuals for additional information.

Output Points

The BitMask Plug-in does not support output. Do not set Location3 to 3 (which indicates an output point for the Interface for OPC DA ) for PI points that are configured for this plug-in.


Chapter 7. Startup Command File

Command-line parameters can begin with a / or with a -. For example, the /ps=M and -ps=M command-line parameters are equivalent.

For Windows, command file names have a .bat extension. The Windows continuation character (^) allows for the use of multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of parameters is unlimited, and the maximum length of each parameter is 1024 characters.

The PI Interface Configuration Utility (PI ICU) provides a tool for configuring the Interface startup command file.

Configuring the Interface with PI ICU

Note: PI ICU requires PI 3.3 or greater.

The PI Interface Configuration Utility provides a graphical user interface for configuring PI interfaces. If the Interface is configured by the PI ICU, the batch file of the Interface (OPCIntn.bat) will be maintained by the PI ICU and all configuration changes will be kept in that file and the module database. See the PI Interface for PI Interface for OPC DA user manual for instructions on creating an instance of the Interface for OPC DA and general interface configuration. The procedure in this section describes the additional steps for using PI ICU to configure the Interface for OPC DA to load the BitMask Plug-in.

In the Interface box, select an instance of the Interface for OPC DA to process bitmask data. The Type box should display OPCInt to confirm that an Interface for OPC DA is selected.

Select OPCInt in the navigation pane on the left. The PI Interface for Interface for OPC DA , which has its own navigation pane, displays on the right. Use the OPCInt page to enter values for the startup parameters that are particular to the Interface for OPC DA instance. After making changes, click Apply to save these changes to the Interface’s startup file and in the module database.

Note: If the Interface instance is running, changes made to the startup file do not take effect until the Interface instance is restarted.

OPCInt Interface Page

Since the startup file of the Interface for OPC DA instance is maintained automatically by the PI ICU, use the OPCInt page to configure interface-specific startup parameters and do not make changes in the file manually. The PI Interface for Interface for OPC DA has 12 sub-pages and its own navigation pane to select a sub-page to display.

This document discusses only the interface configuration parameters that are relevant to the BitMask Plug-in. See the PI Interface for PI Interface for OPC DA user manual for


information on other parameters. The following description of the PI ICU Control identifies the command-line parameter that corresponds to each element of the control.

A yellow text box indicates that an invalid value has been entered or that a required value has not been entered.

OPC ServerConfirm that the OPC Server Node Name and OPC Server Name boxes designate an OPC DA Server.

Plug-Ins

Enter the path to the BitMask Plug-in DLL in the Post Processing DLL box (/dll=path command-line parameter). The BitMask Plug-in file name is OPCPlugInBitmask.dll. The path to this file can be entered into this box from the file browser dialog box that opens by

clicking the button. The file browser dialog box opens in the default folder for plug-in DLLs: [PIHOME]\Interfaces\OPCInt\Plug-Ins. If the BitMask Plug-in DLL is installed in some other folder, browse to the folder that contains the DLL. Select OPCPlugInBitMask.DLL. Click Open to insert the path to the DLL into the Post Processing DLL box and close the dialog box.

Also, the path can be typed or pasted into the Post Processing DLL box.


Command-line Parameters

The following command-line parameters are specifically for the BitMask Plug-in. See the PI Interface for PI Interface for OPC DA user manual for general interface parameters.

Parameter Description

/dll=pathRequired

This is a general interface parameter that specifies the path to a plug-in. Set path to the path to OPCPlugInBitMask.DLL.

/dlldb=#OptionalDefault = 0

Enable the BitMask Plug-in to write additional log messages to trace internal operation. If the Interface for OPC DA is running in an interactive command window, the tracing messages also are written to the command window. Each bit in the value for this parameter enables tracing messages for a main operation of the BitMask Plug-in. The parameter value is the logical OR of the following tracing flags (in hexadecimal notation):

0x01 Initialization and parameter parsing.

0x02 Point loading (point add or edit).

0x04 Point removal (point delete or edit).

0x10 Process OPC input.

0x20 Return results to the Interface.

The parameter value can be represented as a decimal, octal, or hexadecimal integer. Leading “0x” indicates hexadecimal notation (for example, 0x30 to enable tracing while processing OPC input and returning results to the Interface). Leading “0” indicates octal notation (for example, 060 also enables tracing while processing OPC input and returning results to the Interface). Otherwise, the parameter value is interpreted as a decimal integer.The tracing messages enabled by this parameter apply to all PI points.


Chapter 8. Interface Node Clock

Make sure that the time and time zone settings on the computer are correct. To confirm, run the Date/Time applet located in the Windows Control Panel. If the locale where the Interface Node resides observes Daylight Saving Time, check the Automatically adjust clock for daylight saving changes box. For example,

In addition, make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. That is,C:> set

Confirm that TZ is not in the resulting list. If it is, run the System applet of the Control Panel, click the Environment Variables button under the Advanced Tab, and remove TZ from the list of environment variables.


Chapter 9. Starting / Stopping the Interface

This section describes starting and stopping the Interface once it has been installed as a service. See the UniInt Interface User Manual to run the Interface interactively.

Starting Interface as a Service

If the Interface was installed as a service, it can be started from PI ICU, the Services control panel, or with the command:OPCInt.exe -start

To start the interface service with PI ICU, use the button on the PI ICU toolbar.

A message will inform the user of the status of the interface service. Even if the message indicates that the service has started successfully, double check through the Services control panel applet. Services may terminate immediately after startup for a variety of reasons, and one typical reason is that the service is not able to find the command-line parameters in the associated .bat file. Verify that the root name of the .bat file and the .exe file are the same, and that the .bat file and the .exe file are in the same directory. Further troubleshooting of services might require consulting the pipc.log file, Windows Event Viewer, or other sources of log messages. See the “Error and Informational Messages” appendix in the PI Interface for PI Interface for OPC DA user manual for additional information.

Stopping Interface Running as a Service

If the Interface was installed as a service, it can be stopped at any time from PI ICU, the Services control panel, or with the command:OPCInt.exe -stop

The service can be removed by:OPCInt.exe -remove

To stop the interface service with PI ICU, use the button on the PI ICU toolbar.


Chapter 10. Error and Informational Messages

The string BITMASK is prefixed to error messages written to the message log. This string identifies messages written by the BitMask Plug-in and is non-configurable.

Message Logs

The location of the message log depends upon the platform on which the interface is running. See the UniInt Interface Users Manual for more information.

All messages coming from the OPCPlugInBitMask.DLL start with the identifier BITMASK.

In normal operations, only the version of the OPCPlugInBitMask.DLL is logged on startup.

Possible Errors Wrong bit mask: The bitmask is decoded when the tags are loaded, at interface

startup. If the mask cannot be converted to a numeric value, the bit mask is ignored and the tag will be processed normally by the interface, without bitmasking.

No error is logged.

Wrong OPC data type results inBITMASK on Tag tagname not supported (VT_I2 / VT_I4 / VT_UI2 expected)

Bit mask is ignored.

Errors are repeated after a point edit.

Other errors should be handled by the OPC DA interface itself.

Troubleshooting

The /DLLDB startup parameter is also used by OPCPlugInBitMask.DLL. Debug output is written to PIPC.LOG. If the interface is run as a console application, output is sent to the application window, also.

Online switching of the debug level (/DF parameter) is NOT supported.

/DLLDB=1 or greater documents relevant startup information (Actually, here this is just the /DB level itself)

/DLLDB=32 or greater prints out every conversion performed. This is only recommended for a few tags over a short period of time.


System Errors and PI Errors

System errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers.

Error Descriptions on WindowsOn Windows, descriptions of system and PI errors can be obtained with the pidiag utility:Windows \PI\adm\pidiag –e error_number


Chapter 11. Revision History

Date Editor Comments05-Apr-2001 CGoodell Formatting

05-apr-2001 Janelle Beautification

09-Apr-2001 MHesselbach Version 1.0.1: Added specific information

17-Apr-2001 CGoodell / Janelle

Formatting

18-Apr-2001 MHesselbach Added example for decimal format, Message logs

19-Apr-2001 CGoodell Formatting

01-Nov-2005 Janelle Rev A: fixed copyright; made final.

22-Mar-2006 PSluder Added support for VT_UI2 tag datatype.

24-Mar-2006 Janelle Version 2.2.3.0 Rev C: updated template, fixed headers and footers, removed first person references, changed “NT” to “Windows”, updated How to Contact us page

28-Mar-2006 MKelly Version 2.2.3.0 Rev D: updated the section on how to use the DLL using the PI ICU program to configure it.

29-Jun-2006 MKelly Version 2.3.2.0; version number changed to match interface version, DLL rebuilt with UniInt 4.2.3.

23-Feb-2007 Janelle Version 2.3.2.0, Revision A: turned off tracking, accepted all changes, made final

29-Mar-2007 MGrace Add documentation for the pri_bit and pri_bitz (priority bits)

03-Feb-2009 EKuwana Edit the error message (due to wrong OPC data type) in Error and Informational Messages section, by adding VT_UI2 in the error message

01-Jun-2009 LCraven Updated to use dlldb, updated version.

02-Jul-2009 LCraven Minor edits for clarity.

07-Jun-2010 EKuwana Version 2.3.11.2: Edit Priority Bits section regarding placeholder and add an example that utilizes it.

14-Jun-2010 MKelly Version 2.3.11.2 Revision A, Updated to interface user manual skeleton version 3.0.27

11-Mar-13 ALoe Version 2.4.4.0, updated required version of OPCInt


bitmasking plug-in for the opc da...

Documents