Metso Plug-In
for the PI Interface for OPC DA
Version 2.4.4.x
Copyright © 2001-2013, OSIsoft, LLC
OSIsoft, LLC777 Davis St., Suite 250
San Leandro, CA94577USA
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)
Houston, TX
Johnson City, TN
Longview, TX
Mayfield Heights, OH
Philadelphia, PA
Phoenix, AZ
Savannah, GA
Yardley, PA
/ OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSIsoft Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
Calgary, 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
Sales Outlets/Distributors
Middle East/North Africa
Republic of South Africa
Russia/Central Asia / South America/Caribbean
Southeast Asia
South KoreaTaiwan
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, PI Datalink, IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI ManualLogger, PI ProfileView, 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.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph I(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Table of Contents
Introduction
Principles of Operation
Installation Checklist
Plug-In Installation and Administration
Plug-In Directory
Installation Procedures
Define Required Digital States
Modify OPCInt.BAT
Configure PI Tags
Upgrading the Plug-In
Moving the Plug-In to a New Directory
Uninstalling the Plug-In
Command Line Parameters
Error and Informational Messages
Message Logs
Troubleshooting
System Errors and PI Errors
Appendix A: Use of AddOPCPlugInStates.bat
Appendix B: OPCPlugInMetso.INI Configuration File
Revision History
1
Metso Plug-In DLL for OPC Interface to the PI System1
Introduction
The PI Interface for OPC DA will retrieve all data from an OPC server, but when data stops flowing because of an emergency, the operator needs to know that there is a problem. Without modification, the OPC DA interface simply shows data when it is available, and ignores the reason it has stopped flowing. PI users need information about a datum’s specific error condition. PI data tags may become invalid for several reasons. A paper machine, for instance, may have a sheet break. In order to get complete information from the sensor gauge (through OPC), a plug-in DLL for the OPC DA interface has been created by OSIsoft, LLC. For the (Valmet-Neles) Metso system, this plug-in is called OPCPlugInMetso.DLL.
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 versions of the OPC DA interface.
1
Metso Plug-In DLL for OPC Interface to the PI System1
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,’ the Extended Descriptor attribute (see the PI Interface for OPC DA manual for exact tag configuration details). The primary type of data retrieved from paper machines is profile data. These data are configured as array data (please see the PI Interface for OPC DA manual for proper configuration of array tags). Data is also available which indicates various statuses of the paper machine as well as the starting and ending boxes for valid profile data.
Every time array data is read, the plug-in, OPCPlugInMetso.DLL, examines the statuses associated with that data. If a given status condition is in effect, the plug-in will set the values for some or all of the array data with the system digital state associated with the error condition. If no status condition exists, the array data is sent to PI with no modifications.
Profile data is the only data for which special statuses will be applied. No other tags are affected. The status conditions which may invalidate a profile tag, and the digital state value which that tag acquires in that error condition are as follows:
OffSheetEdge:
Scanner does not normally reach that data box position. The plug-in will write the digital state, OffSheetEdge, to the profile tags that are in positions less than the start box and which are in positions greater than the end box. Tags specifying the minimum and maximum valid data boxes for each profile are required for the plug-in to perform this function.
SheetBreak:
Sheet-break has been detected on the frame. All profile tags associated with that scanner will have the status SheetBreak written to them.
Standardize:
Frame is in standardize mode. All profile tags associated with that scanner will have the status Standardize written to them.
FrameOffline:
Frame is in a state which does not produce data, such as ‘Dead’, ‘Unavailable’, ‘Emergency Stop’, ‘Manual’, ‘Console Offsheet’, etc., which is not covered by the specific conditions described by other PI states.
SinglePoint:
Gauge on the same scanner has gone into single-point mode, which disables all gauges on the scanner from normal profile sampling. The results of single-point (or ‘buffered single-point’) sampling may be accessed through other (non-profile) Metso OPC variables (InstrumentTag).
1
Metso Plug-In DLL for OPC Interface to the PI System1
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps get the OPC DA interface up and running with the OPCPlugInMetso.DLL. If not familiar with the plug-in, return to this section after reading the rest of this manual in detail.
Follow the steps in the order listed below.
- Install the PI ICU which will install the PI SDK and PI API.
- Install the PI Interface for OPC DA.
- Define required digital states in the SystemDigitalState table
OffSheetEdge
SheetBreak
Standardize
FrameOffline
SinglePoint - Use the PI ICU to configure the OPC DA interface and use the Plug-Ins configuration to add the support for the OPCPlugInMetso.DLL or modify OPCInt.BAT to activate the DLL.
- Configure PI tags.
- Start the interface.
1
Metso Plug-In for the PI Interface for OPC DA1
Plug-In Installation and Administration
Plug-In Directory
The OPCPlugInMetso.DLL is installed as part of the PI OPC DA interface installation into the Plug-in subdirectory. For instance, if the interface is installed in
D:\PIPC\Interfaces\OPCInt
then the DLL will be installed in
D:\PIPC\Interfaces\OPCInt\Plug-Ins
Installation Procedures
Although the OPCPlugInMetso.DLL is on the CD with the OPC DA interface, the user must configure some things before the DLL will be activated.
Define Required Digital States
OffSheetEdge,SheetBreak, Standardize, FrameOffline, and SinglePoint digital statesmust be defined before the OPC DA interface can run with the plug-in. The states are not case sensitive, but they must be spelled exactly as shown.
The DLL expects these digital states to be somewhere in the System Digital State Set. There is a program in the plug-ins directory supplied to add these states automatically. See “Appendix A: Use of AddOPCPlugInStates.bat,” p13.
Modify OPCInt.BAT
OSIsoft recommends using the PI Interface Configuration Utility for making changes to the interface batch file. Under the opcint tab there is a Plug-Ins item that is used to configure the DLL, which an instance of the OPC DA interface will use. This will add the /DLL= command line parameter to the batch file.
For Example”
/DLL=C:\PIPC\Interfaces\OPCInt\Plug-Ins\OPCPlugInMetso.DLL
This plug-in requires a configuration file. Once this DLL is selected in the PI Interface for OPC DA - ICU Control another text box will open and allow for the configuration file to be picked. Use the browse button on the right to search for the directory and name of the configuration file. This will add another command line parameter to the batch file. This also can be added to the batch file manually.
/DLLConfig=c:\PIPC\Interfaces\OPCInt\Plug-Ins\OPCPlugInMetso.INI
Once this has been added to the batch file either manually or by using the PI ICU the OPC DA interface will automatically load the plug-in at startup. If the interface is already running, the interface must be restarted for the DLL to be activated.
Note: The “^” shown at the end of all lines in the command file, except for the last line, is a continuation character indicating that more command lines follow.
If the path name contains spaces, the whole /DLL startup parameter has to be surrounded by double quotes. Example:
/DLL=”C:\PIPC\Interfaces\OPCInt\Plug-Ins\OPCPlugInMetso.DLL”
Configure PI Tags
The plug-in needs extra information from Metso to adjust the profile tags’ status. This is accomplished by creating a few more PI tags. For each Metso scanner (defined by <machine/scanner Id>s named in the IN-file. Ex: “pr:1-S1”), the following tags should be created. The OPC symbol for a Metso variable is in the InstrumentTagattribute of the PItag that will receive its data.
Note: all OPC symbols are case-sensitive.
Starting and Ending Data Boxes
:e:<machine/scannerID>OF0S:c1
First valid box, forward-direction. This is used by the plug-in to determine valid starting data box, when the scanner is moving in the forward direction. For a forward scan, a digital state of OffSheetEdge will be written to each tag in profile array positions from one to the value sent to this tag minus one. Example InstrumentTag: “:e:pr:1S1OF0S:c1”.
:e:<machine/scannerID>OF0S:c2
Last valid box, forward-direction. This is used by the plug-in to determine the last valid data box, when the scanner is moving in the forward direction. For a forward scan, a digital state of OffSheetEdge will be written to each tag in profile array positions from the value sent to this tag plus one, to the last tag in the profile.
:e:<machine/scannerID>OF0S:c3
First valid box, reverse-direction. Same information as ‘First-valid-forward-direction’, except applied to reverse-direction scans.
:e:<machine/scannerID>OF0S:c4
Last valid box, reverse-direction. Same information as ‘Last-valid-forward-direction’, except applied to reverse-direction scans.
:e:<machine/scannerID>OF0M:ev20
Forward-direction scan started. This, combined with the following two tags, tells the plug-in whether a particular profile was gathered in the forward or the reverse direction, enabling the plug-in to select the correct first/last box variables. Example InstrumentTag: “:e:pr:1-S1OF0M:ev20”.
:e:<machine/scannerID>OF0M:ev21
Forward-direction scan ended. (see above)
:e:<machine/scannerID>OF0M:ev22
Reverse-direction scan started. (see above)
Standardize
:e:<machine/scannerID>OF0MODE:sz
When the scanner goes into standardize mode, the Standardize digital state will get written to each profile tag in all profiles associated with the given scanner. Example InstrumentTag: “:e:pr:1-S2OF0MODE:sz” (e.g. machine 1, scanner 2).
SheetBreak
:e:<machine/scannerID>OF0M:ev6
The SheetBreak digital state will get written to each profile tag in all profiles associated with the given scanner. . Example InstrumentTag: “:e:pr:2-S1OF0M:ev6” (e.g. machine 2, scanner 1).
SinglePoint
:e:<machine/scannerID>OF0MODE:fp
The SinglePoint digital state will get written to each profile tag in all profiles associated with the given scanner. . Example InstrumentTag: “:e:pr:2S3OF0MODE:fp” (e.g. machine 2, scanner 3).
Offline
:e:<machine/scannerID>OF0MODE:sc
‘Scanning’ flag, which, when false, causes all profile tags on that scanner to be marked Offline. Example InstrumentTag: “:e:pr:1-S3OF0MODE:sc” (e.g. machine 1, scanner 3).
Upgrading the Plug-In
If the plug-in is upgraded independent of the OPC DA interface, install the plug-in in the appropriate directory. Then stop and restart the OPC DA interface according to the instructions in the PI Interface for OPC DA manual.
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.batmust be updated to reflect the name of the new directory and the interface must be restarted as described in the PI Interface for OPC DA manual.
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 or delete the /DLL=and /DLLConfig= command-line parameters from the batch file, and stop and restart the OPC DA interface according to the instructions in the PI Interface for OPC DA manual.
1
Metso Plug-In for the PI Interface for OPC DA1
Command Line Parameters
The DLL supports a few command-line parameters that are specific to this DLL. These parameters are different from interface specific parameters. When the DLL is loaded by the interface, the interface passes all command-line parameters. Some of the parameters that the interface uses are also used by the DLL. For example, /ID and /HOST.
DLL specific parameters:
Parameter / Description/DLLConfig=<filespec>
Required / Configuration file. This file defines how the interface recognizes profile tags and the status tags which are applied to them. See the Appendix B: OPCPlugInMetso.INI Configuration File for more details.
/DLLDB=#
(Default: 0)
Optional / Debug level (0-32767). The higher the number the more verbose the messages printed.
1
Metso Plug-In for the PI Interface for OPC DA1
Error and Informational Messages
Error messages that are written to the message log are pre-pended by a string NameID. Name is a non-configurable identifier that is no longer than 9 characters. IDis a configurable identifier that is no longer than 9 characters and is specified using the /idflag on the startup command line.
Message Logs
Error and informational messages are written to the pipc.log file. The location of the pipc.log file is determined by the PIHOME entry in the pipc.ini file. The pipc.ini file should always be in the %windir%directory. For example, if the PIHOMEentry is:
C:\PIPC
then the pipc.logfile will be located in the c:\PIPC\dat directory.
For version 1.3 and greater of the PI API, a process called pilogsrvmay be installed to run as a service. After the pipc.log file exceeds a user-defined maximum size, the pilogsrvprocess renames the pipc.log file to pipcxxxx.log, where xxxx ranges from 0000 to the maximum number of allowed log files. Both the maximum file size and the maximum number of allowed log files are configured in the pipc.ini file. Configuration of the pilogsrv process is discussed in detail in the PIAPIInstallationInstructions manual.
Note: No messages are written to the command window when the interface is run interactively. All messages are written to pipc.log.
Troubleshooting
Restarts: The Metso server must be operational before starting the OPC DA interface.
- Removing the Ethernet cable and reconnecting it while the interface is operating recovers within about one minute and no user action is required.
- Powercycling the API data collector node starts up without user action.
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 Windows
On Windows, descriptions of system and PI errors can be obtained with the pidiag utility:
\PI\adm\pidiag –e error_number
1
Metso Plug-In for the PI Interface for OPC DA1
Appendix A: Use of AddOPCPlugInStates.bat
This option is only available when the PI Home Node is PI 3.
The plug-in requires several new digital states in the PI System Digital State Set that can be built automatically using an application called AddOPCPlugInStates. The application consists of the following four files that are located in the Plug-Ins\Utilities directory underneath the OPC DA interface directory:
- AddOPCPlugInStates.bat
- NewStates.bat
- AddStates.exe
- MakeDumpSet.exe
All of these files must be moved to the PI\adm directory of the PI 3 home node. They will not function unless moved to the PI home node, in the PI\adm directory. Log in as an administrator, go to a DOS prompt, and change directory to the PI\adm directory. Make sure PI is running. Invoke:
AddOPCPlugInStates
The required digital states will be added to the PI System Digital State Set.
1
Metso Plug-In for the PI Interface for OPC DA1
Appendix B: OPCPlugInMetso.INI Configuration File
The plug-in requires a configuration file, which is supplied as a command-line parameter in the startup batch file for the OPC DA interface; for example: