Max Control Systems maxDNA
Interface to the PI System
Version 1.3.0.1 – 1.4.1.0
Rev E
How to Contact Us
Phone / (510) 297-5800 (main number)(510) 297-5828 (technical support)
Fax / (510) 357-8136
E-mail /
World Wide Web / http://www.osisoft.com
Mail / OSIsoft
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrabe 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 OSI Software, 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_maxDNA.doc
Ó 1999-2004 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
Table of Contents
Introduction 1
Supported Features 1
Diagram of Hardware Connection 3
Principles of Operation 5
Installation Checklist 7
Interface Installation 9
Naming Conventions and Requirements 9
Interface Directories 9
The PIHOME Directory Tree 9
Interface Installation Directory 10
Interface Installation Procedure 10
Installing the Interface as an NT Service – Not Recommended 10
Installing the Interface Service with PI-Interface Configuration Utility 11
Installing the Interface Service Manually 13
Digital States 15
PointSource 17
PI Point Configuration 19
maxDNA Tag Address Format 19
General PI Tag Configuration Information 19
Tag 19
PointSource 19
PointType 19
Location1 20
Location2 20
Location3 20
Location4 20
InstrumentTag 21
ExDesc 21
Scan 21
Shutdown 21
SourceTag 22
ExcMin, ExcMax, ExcDev 22
Output Points 22
Trigger Method 1 (Recommended) 23
Trigger Method 2 23
When do "Events" Occur? 23
Quality Points 23
Watchdog Points 24
Performance Point Configuration 25
I/O Rate Tag Configuration 27
Monitoring I/O Rates on the Interface Node 27
Configuring I/O Rate Tags with PI-ICU (NT-Intel) 27
Configuring I/O Rate Tags Manually 28
Configuring the PI Point on the PI Server 29
Configuration on the Interface Node 29
Startup Command File 31
Command-line Parameters 31
Sample Startup Command File 34
Interface Node Clock 35
Security 37
Starting / Stopping the Interface 39
Interactive Startup 39
Automatic Startup – Suggested Method 39
Stopping the Interface 40
Buffering 41
Configuring Buffering with PI-ICU (NT-Intel) 41
Configuring Buffering Manually 44
Example piclient.ini File 45
Appendix A: Communication Error Recovery 47
Appendix B: Troubleshooting 49
Frequently Asked Questions 49
Message Logging 49
Logging Configuration 50
Run Time Logging Configuration 50
Revision History 53
Max Control Systems maxDNA Interface to the PI System 25
Introduction
This is a description of the PI-maxDNA Interface (formally known as the Max Controls Max1000 Plus+ Interface) to the PI System. The interface can be run on one of the following:
· A Windows 2000 or XP PI 3 Server
· A Windows 2000 or XP PI Interface node with network access to a PI 2 or PI 3 Server
Note: The interface requires that the maxDNA software be present on the same PC as the interface and the PC have network access to the SBP.
Migration interfaces are available to connect PI to all generations of MAX systems. The minimum requirement is that a maxDNA DBM must be present.
Note: The customer must contact MCS to run a system analysis to determine available throughput on older systems.
For proper interface operation, the user must configure points (tags) on a PI 2 or PI 3 home node (the words "point" and "tag" are used interchangeably in this manual). Tags are used to update and receive data from maxDNA members. A single interface can collect data from one or more maxDNA members at a time. Data is received at a given frequency. All values that are written to the snapshot or archive use the system time from the PI home node.
At startup, the interface scans the PI Point Database for all associated points and builds its own point list. During runtime, the interface continues to check the PI Point Database for point updates and modifies its point list accordingly. If the Scan field of any point on the point list is set to off, the point is removed from the point list. The point is added once again after the Scan field is turned back on. If a fixed scan rate cannot be found for a given point, the point will be removed from or will not be added to the point list.
Supported Features
Feature / Support /Part Number / PI-IN-MCS-PLUS-NTI
Platforms / NT Intel (2000, XP)
PI Point Types / float16, float32, float64, int16, int32, digital
Sub-second Timestamps / No
Sub-second Scan Classes / N/A (unsolicited data)
Automatically Incorporates PIPoint Attribute Changes / Yes
Exception Reporting / Yes
Outputs from PI / Yes
Inputs to PI: Scan-Based / Unsolicited / Event Tags / Unsolicited
Maximum Point Count / Unlimited
Uses PI-SDK / Yes
PINet to PI 3 String Support / N/A
* Source of Timestamps / maxAPPS (Software Backplane)
History Recovery / No
* Failover / Interface failover – no
Software Backplane failover - Yes
* UniInt-based / Yes
* Vendor Software Required on PI-API / PINet Node / Yes
* Vendor Software Required on Foreign Device / Yes
* Vendor Hardware Required / Yes
* Additional PI Software Included with Interface / Yes
* Device Point Types / int16, int32, float16, float32, float64, digital
* See paragraphs below for further explanation.
Source of Timestamps
Timestamps are generated by the maxAPPS software, which is running on the same machine as the interface.
Failover
The maxDNA Interface does not itself support failover. However, the Software Backplane does handle failing over from one DPU to another. In most cases, the interface needs to re-subscribe its points after a failover. Virtual DPU as well as physical DPU failover has been tested.
Note: When recovering a failed virtual DPU in primary/backup mode, make sure the backup DPU is started completely before starting the primary DPU. This is to make sure the primary DPU is able to load its point list correctly. Otherwise, re-subscribe attempts will fail.
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 maxDNA 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.
Because UniInt version 3.5.8 or later was used to create version 1.4.1.0 or later of the PI-maxDNA Interface, msvcp71.dll, msvcr71.dll and atl71.dll are required to be on the interface node. These three dlls are included in the interface install kit on CD, and are also normally installed with Microsoft’s .NET Framework version 1.1. If these files are not installed, then installing version 1.3.1 or greater of the PI-SDK will install them.
Vendor Software Required
Software Backplane is the generic name given to the software that runs between the interface and the DPUs. It consists of several parts. The relevant ones for this interface are maxAPPS and maxSTATION. maxSTATION is the full version of the software distributed by Metso Automation (formerly MAX Controls). It runs on its own machine. maxAPPS is the software that is needed on the interface node.
Vendor Hardware Required
The Software Backplane connects to the DPUs that are used to collect plant data. The DPUs can be physical DPUs or virtual DPUs (software emulation of hardware).
Additional PI Software
The PI-SDK is included on the PI-maxDNA Interface CD.
Device Point Types
The Software Backplane supports int16, int32, float16, float32, and float64 point types for data, and digital types for quality reporting.
Diagram of Hardware Connection
Max Control Systems maxDNA Interface to the PI System 25
Principles of Operation
The maxDNA SBP uses “subscriptions” to mark data points for frequent update. The interval between updates is configurable on a point-by-point basis. The maxDNA system only sends data to a client when an exception has occurred. An exception occurs if the value changes by more than the given dead band, or the exception maximum time has expired and the dead band (exception deviation) has not been exceeded.
When the Interface first starts up, it establishes communication with PI. A connection to the local maxDNA server is then established. The connection is uniquely identified by the client with a “user name” parameter, and uniquely identified to the server by an identification number. The interface to the maxDNA system can subscribe, unsubscribe, and read from specific data points. It also has the ability to write to a designated WatchDog tag on the maxDNA system, which can be optionally configured by the user. All data handled by the maxDNA SBP is done with variant data types. This means that when data is assigned to a tag, the data is automatically handled using the most compatible type. The maxDNA SBP has comparable data types to handle all types supported by PI.
Exception reporting is done on the maxDNA system using the PI exception parameters which are passed to it during subscription. As each point belonging to the interface is identified, the interface subscribes the maxDNA point (specified in the InstrumentTag and/or the ExDesc) on the SBP. The exception minimum (ExcMin), exception maximum (ExcMax), and exception deviation (ExcDev) (in engineering units) are also sent to the SBP. The maxDNA system will check to see if the point subscribed is valid, and if it is valid, can it be accessed. An error code is returned if the point is invalid or cannot be accessed and the interface will print a message that it could not be subscribed.
Note: Some points may not be accessible at interface startup, but once they do become accessible, data will automatically start being collected for them. Prior to data collection, the digital state CONFIGURE is written to all points. This allows the user to easily determine which points have not begun collecting data. If connection is lost to the maxDNA system, I/O Timeout is written to all the input tags. BAD INPUT is written to points when any other error is returned from the maxDNA system.
The maxDNA system uses the PI exception specifications that are passed for a point to determine when to check for an exception and determine when an exception has occurred. An exception occurs when the maxDNA tag exceeds the ExcDev for the point or the ExcMax time has been exceeded with no exception occurring. The ExcMin time controls the frequency at which exceptions are checked. The minimum exception minimum time passed to the maxDNA system is 1 second. If a tag has its ExcMin parameter set to 0, then a value of 1 will be passed to the maxDNA system. The maximum exception maximum time passed to the maxDNA system is 30 seconds if the /excmax flag isn't used. The /excmax flag can be used in the interface startup file to set the maximum exception maximum parameter for all tags to a value greater than 30 seconds. If /excmax isn’t set in the interface startup file and a tag has its ExcMax parameter set greater than 30 seconds, then a value of 30 will be passed to the maxDNA system. If /excmax is set in the interface startup file and a tag has its ExcMax parameter set greater than /excmax, then the /excmax value will be passed to the maxDNA system. Please consult your MAX Control Systems representative for recommendations for exception maximum settings. Typical systems will be able to handle ExcMax times of 30 seconds for all tags. However older systems may not.
Since exception reporting is done on the maxDNA side no further exception reporting is done within the interface. Value and quality data are sent to PI when they are received by the interface. Although the scan frequency is not used, the Location4 parameter for all input points must still be set to one.
Max Control Systems maxDNA Interface to the PI System 25
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps you get the PI-maxDNA Interface running. If you are not familiar with PI interfaces, you should return to this section after reading the rest of the manual in detail.
1. Verify that the maxAPPS software is installed and is working correctly.
2. Install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API)
3. Verify that PI-API has been installed.
4. Install the interface.
5. Define digital states, if quality tags are being used.
6. Choose a point source. If PI 2 home node, create the point source.
7. Configure PI points.
Location1 is the interface instance.
Location2 is whether the tag is an input (0), output (1), or watchdog (2) tag.
Location3 is whether the tag is a value (0) or quality (1).
Location4 is the scan class.
Location5 is not used.
ExDesc is not used unless the member portion of the point address is omitted in the InstrumentTag.
InstrumentTag is the point address on the Software Backplane.
8. Configure I/O Rate tag.
9. Edit startup command file using the PI-ICU.
10. Set interface node clock.
11. Set up security.
12. Start the interface without buffering.
13. Verify data.
14. Stop interface, start buffering, start interface.
Max Control Systems maxDNA Interface to the PI System 25