Yokogawa YGW
Interface to the PI System
1.8.0.1
1
UniInt End-User Interface to the PI System
How to Contact Us
Phone / (510) 297-5800 (main number)(510) 297-5828 (technical support)
Fax / (510) 357-8136
E-mail /
World Wide Web /
Mail / OSIsoft
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrae 30
D-63674 Altenstadt 1
Deutschland / OSI Software, Ltd
P O Box 8256
Symonds Street
Auckland 1035 New Zealand
OSI Software, Asia Pte Ltd
152 Beach Road
#09-06 Gateway East
Singapore, 189721
Unpublished – rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Trademark statement—PI is a registered trademark of OSIsoft, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HPUX is a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.
PI_YGW.doc
1997 - 2005 OSIsoft, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
1
UniInt End-User Interface to the PI System
Table of Contents
Introduction
Reference Manuals
Supported Features
Communication Configuration
Yokogawa Gateway Setup Diagram
Hardware Configuration
Micro XL Communication Requirements
Ethernet Communication
Serial Communication
Principles of Operation
Gateway Failover
Input Tags
Output Tags
Tag Attributes Update
Event Counter Tags
Logging File
Error Handling
Installation Checklist
Interface Installation on NT
Naming Conventions and Requirements
Interface Directories
The PIHOME Directory Tree
Interface Installation Directory
Interface Installation Procedure
Installing the Interface as an NT Service
Installing the Interface Service with PI-Interface Configuration Utility
Installing the Interface Service Manually
Interface Installation on VMS
Naming Conventions and Requirements
Interface Installation Procedure
Permanent Installation
Communication Testing Programs
Digital States
PointSource
PI Point Configuration
Point Attributes
Tag
PointSource
PointType
DigStartCode, DigNumber (PI2 only)
DigitalSet (PI3 only)
Location1
Location2
Location3
Location4
Location5
InstrumentTag
ExDesc
Scan
Shutdown
SourceTag
Zero/Span
Performance Point Configuration
Configuring Performance Points with PI-ICU (NT-Intel)
Configuring Performance Points Manually
I/O Rate Tag Configuration
Monitoring I/O Rates on the Interface Node
Configuring I/O Rate Tags with PI-ICU (NT-Intel)
Configuring I/O Rate Tags Manually
Configuring the PI Point on the PI Server
Configuration on the Interface Node
Startup Command File
Configuring the Interface with PI-ICU
ygw Interface Tab
Command-Line Parameters
Sample YGW.bat File
Interrupt Messages Switch File
Data I/O Type Filter File
Digital State String Translation File
Interface Node Clock
NT
VMS
Security
NT
VMS
Starting / Stopping the Interface on NT
Starting Interface as a Service
Stopping Interface Running as a Service
Starting / Stopping the Interface on VMS
Starting a Detached Process
Stopping
Buffering
Configuring Buffering with PI-ICU (NT-Intel)
Configuring Buffering Manually
Example piclient.ini File
Appendix A: Error and Informational Messages
Message Logs
Messages
System Errors and PI Errors
Revision History
1
Yokogawa YGW Interface to the PI System1
Introduction
The Yokogawa YGW interface provides communication between PI and Yokogawa CGWU, EGCW3 and ECGW* gateways and the Micro XL DCS. It is an OSI Software standard Universal Interface (Uniint).
Note: All mention of the above four Yokogawa systems will be referred to, hereafter in this manual, as “the gateway”. If, however, information in this manual refers to a specific gateway, the actual gateway name will be used.
Data is transferred between the gateway and the interface via RS-232 Serial TTY communication or TC/PIP socket calls. Data is transferred between the interface and PI via the PI API. The PI API is necessary for the interface to run and is not included with the interface. The minimum requirements for the interface are given in the following table:
VAX/Alpha VMS / All / 2.1.1 / N/A
Intel Windows NT / 3.51 / 3.1 / 1.2
Alpha Windows NT / 4.0 / 3.1 / 1.2
The interface supports input tags (from Yokogawa to PI) and output tags (from PI to Yokogawa). It counts the events to and from these tags, including exception tests, and sends its totals periodically to PI. Data from the gateway is received at cyclic frequencies or by exception in the data. The frequency of the cycles is configured by the user and controlled by the interface. The number of tags that the interface is capable of servicing is unlimited.
Changes that are made to the PI point database are reflected in the interface. This includes the adding, editing and deleting of tags.
All error information and some summary information are output to a log file. The amount of summary information that is output is configurable by the user and is minimal by default. For information about configuring information messages, see the “/db”, “/lg” and “/cl” headings of the Command-Line Parameterssection on page 50
Reference Manuals
OSIsoft
- PI Server manuals
- PI-API manual
- UniInt End User Document
Supported Features
Feature / SupportPart Number / PI-IN-YO-YGW
Platforms / VMS / Alpha VMS / NTI (4, 2000, XP)
APS Connector / No
Point Builder Utility / No
ICU Control / Yes
PI Point Types / Real, digital, int16, int32, float16, float32, float64, string
Sub-second Timestamps / No
Sub-second Scan Classes / No
Automatically Incorporates PIPoint Attribute Changes / Yes
Exception Reporting / Yes
Outputs from PI / Yes
Inputs to PI: Scan-based / Unsolicited / Event Tags / Scan-based, Event tags
Maximum Point Count / Limited only by YGW gateway
Uses PI-SDK / No
PINet to PI 3 String Support / No
Source of Timestamps / PI Server
History Recovery / No
Failover / No
* UniInt-based / Yes
Vendor Software Required on PI-API / PINet Node / No
* Vendor Software Required on Foreign Device / Yes, only for Micro XL. See Micro XL Communication Requirements section below.
* Vendor Hardware Required / Yes, only for Micro XL. See Micro XL Communication Requirements section below.
* Additional PI Software Included with Interface / Yes, YGI_Test.exe and YGI_TestB.exe connection test programs
Device Point Types / INT, FLT, CHR
* See paragraphs below for further explanation.
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 PI-Yokogawa YCG interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of our interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniIntsupplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.
The UniInt End User Document is a supplement to this manual.
Vendor Software Required
Vendor software is required only if the interface is connecting to a MicroXL Device. This is described below in the Micro XL Communication Requirements section below.
Vendor Hardware Required
A network interface card is required on the gateway (or MicroXL device) if the interface is to be connected using Ethernet TCP/IP. This card is supplied by Yokogawa and is sometimes provided with the device by default..
Additional PI Software
See section Communication Testing Programs on page 25 for explanation.
Communication Configuration
The interface supports communication to a variety of Yokogawa systems using different communication protocols. The following table indicates which protocols are supported for each Yokogawa system:
Centum V / RS-232C TTY / CGWU / VMS, Windows NT
Centum XL / RS-232C TTY / ECGW* / VMS, Windows NT
ECGW2 / VMS, Windows NT
ECGW3 / VMS, Windows NT
Ethernet TCP/IP / ECGW3 / VMS, Windows NT
Micro XL / RS-232C TTY / No Gateway / VMS, Windows NT
Ethernet TCP/IP / Software Emulator / VMS, Windows NT
Note: If the interface is running on VMS, DEC TCP/IP software (UCX) is required to be able to use the TCP/IP protocol.
Yokogawa Gateway Setup Diagram
Hardware Configuration
To be able to communicate with the gateway, the correct protocol parameters must be set up on the DCS.
Ethernet TCP/IP
The following information must be specified at the DCS:
Communication Text / Character Mode / Binary Mode
Delimiter Character / CR-LF / None
Sequence Numbers / Yes / Yes
Interrupt Message Mode / Character Mode / Character Mode
See the Command-Line Parameterssection on page 50 for information about how to match the interface with these parameters.
Text can be sent continuously to gateway without waiting for reply. The maximum text count that can be sent in sequence depends on the configuration of each gateway. The continuous text count is specified in the interface startup file using the “/sc” argument (see page50) and should not exceed the limits of the DCS.
RS-232 Serial Communication
The following information must be specified on the DCS and in the interface port settings file, PISysExe:Ygi_Setterm.com (VMS only) or the interface startup file command line arguments (NT only). The protocol does not accept sending text continuously. The settings marked (opt) are optional but must match between the DCS and the port settings.
Communication Rate / 9600 bps (opt) / 9600 bps (opt) / /bps=9600
Communication Code / 8 bit (opt) / 8 bit (opt) / /bs=8
Parity / Even (opt) / Even (opt) / /par=E
Stop Bit / 1 bit / N/A / /sb=1
Text / ASCII / N/A / N/A
XON/XOFF / Yes / N/A / N/A
Sequence Numbers / Yes / N/A / N/A
Other Settings / N/A / NoWrap, NoType_Ahead, NoModem / N/A
Micro XL Communication Requirements
The MicroXL does not have a gateway through which to collect data (see the Yokogawa Gateway Setup Diagramabove). Communication is done via a communication interface card, it’s driver and some additional communications software. All of these are installed on the MicroXL. The communication software provides an interface to the MicroXL that gives it the appearance of an ECGW3 gateway. Thus the interface can send and receive its normal protocol as if it were connected to a gateway.
The requirements for serial communication and Ethernet communication are as follows:
Ethernet Communication
Yokogawa Products
- EN83 Ethernet communication card (the Ethernet card for the MIGHTY station).
- MAPF-S221 Ethernet card driver.
- MAPF-S311 Ethernet computer communications package (ECGW3 protocol emulation software).
Third Party Products
- Transceiver and cable converter from AUI port to the physical network.
The MOPS and MOPL stations must be upgraded to MIGHTY stations (Y211). The setup will not function on standard (S211), advanced (A211) or enhanced (E211) systems. These systems may have an EN82 Ethernet card but MAPF-S311 emulation software will not work with it.
To be sure of what version the station is currently running, reboot the operator station, press the S2 key and check the operating system revision number at the top of the screen. The MIGHTY software will display “R1.A#” (where # is the revision number). The revision number itself is not important (R1.A6 is the Y2K compliant revision but subsequent revisions may have been released since), as long as the revision label is R1.A on the S2 screen. If the station is not a MIGHTY station then the revision label will display “Rev.#” or something similar.
The station can also be checked for its version by looking at the CPU card (it is a CP81 card). A card of type CP81*E is a MIGHTY type card. Cards of type CP81*A through to CP81*D are not.
Station Type / Station Number / Y2K Revision / CPU CardStandard / S211 / Rev.26 / CP81*A
Advanced / A211 / Rev.26 / CP81*B
Enhanced / E211 / Rev.26 / CP81*C
Power / Rev.26 / CP81*D
MIGHTY / Y211 / R1.A6 / CP81*E
Performance is most reliable when the Ethernet card is in the engineering station (or wherever the system is configured from). The MOPS or MOPL station must be given a fixed IP address because DHCP is not supported.
Serial Communication
- RS81 serial communication card (the Serial card for MOPS or MOPL stations).
- MSPF-C011 serial communication card driver.
- MAPF-S031 serial computer communications package (ECGW3 protocol emulation software).
The serial port settings must match those in the table in the RS-232 Serial Communication section above.
1
Yokogawa YGW Interface to the PI System1
Principles of Operation
When the interface starts up, it receives several parameters from the interface startup file. These parameters define the PI Point Source code and the set of Scan Class time periods to be available and other parameters as described in the Command-Line Parameterssection on page50.
Log messages are recorded either in the PI log file or the PI application log file. The PI log file is named PI\PILog\pimsg_yymmdd.dat and is renewed daily. Its information is more about the status of PI than the interface. The status of the interface is recorded in the PI application log file Pipc\Dat\Pipc.log. This file is never renewed and is the responsibility of the system administrator to handle its backing up and/or deleting.
The interface begins by searching the PI Point Database for all tags configured with the PointSource code specified in the interface startup file. It records these tags in dynamic group structures in computer memory based on logical grouping (for example, one list per scan class, per point type). If any tag makes reference to a PI tag that is not present in the PI point database, a message indicating this is logged and the tag is rejected by the interface.
Data is retrieved from the gateway upon request. The conditions under which this happens are specified either by individual PI tags or by the interface startup file as described in the Command-Line Parameterssection on page 50.See, also, the Input Tags section below. When the interface receives data it is filtered through the exception and compression criteria of each PI tag.
When the interface process has completed these initial tasks, it enters a permanent loop in which it processes input and output tags. This loop is repeated until the interface is stopped. The actions taken within this loop are described below.
Gateway Failover
The interface is able to maintain connection information for multiple gateways. If the connection to a gateway fails, the interface will be able to connect to a different gateway.
The interface maintains information about each gateway in a list. This gateway information is specified in the interface startup file. Each gateway in the list may be of a different type and/or connection type, provided the interface can support it. See the “/gw” argument on page 58and the “/term” argument on page 60for information about how to configure the interface for each gateway.
When the interface attempts to make a connection, it starts with the first gateway in its list and attempts to connect to it. If this fails, it tries the second gateway, then the third, until all of the gateways that have been specified in the interface startup file have failed.
Note: The interface can maintain information for a maximum of 10 different gateway connections.
When the interface encounters a connection failure during operation it will attempt to reconnect by starting at the beginning of its gateway list. This occurs even if it was connected to a gateway that is second or later in the list. For this reason, the gateway that is considered to be the primary source of data collection for the interface (the one that is used under normal circumstances) should be the first in the list. Other gateways are considered merely as backup and should be placed in the list according to their appropriate priorities. This way, the interface will reconnect to its preferred gateway if it is available—especially if the connection was lost only temporarily.
Note: The interface will not automatically switch to another gateway that has a higher priority just because that gateway is made available. The current connection must be broken before the interface will attempt to reconnect. For example, the connection to gateway 1 is lost and the interface finds a connection to gateway 2, it will not switch back to gateway 1 until the connection to gateway 2 is broken.
Some useful applications of this functionality are:
- If a gateway needs to be taken offline or shut down for a long period of time, the interface can still collect data without the need for human interaction and reconfiguration.
- If the there is a network problem and the Ethernet connection fails, the interface can connect to the same gateway using RS-232 via a serial line.
Input Tags
Input tags are serviced by the interface to collect data from the gateway and send it to PI. They can either be scan-based or event-based. Scan based tags are serviced regularly at a pre-defined time interval. Event based tags are serviced when a change occurs in a separate PI tag.
Scan-Based
An input tag can be configured to be updated at a regular time interval specified by any one of a set of user-defined scan classes. The interval of each scan class is based from and controlled by the interface. When a scan class’s time interval expires, the data for the tags that are configured for that scan class is requested. 32 tags for a particular scan class are retrieved from the gateway at a time, until all tags for that scan class are collected. For information about defining scan-based input tags, see the description of “/f” in the Command-Line Parameterssection on page61.
Event-Based
An input tag can be configured to send data to PI on an event, based on the exception of the data from a separate PI point. When the value of this separate PI point changes, the data for the actual tag is requested from the gateway. For information about setting up an exception tag, see theExDesc heading of the PI Point Configurationsection on page 37
Output Tags
Output tags are serviced by the interface to collect data from PI and send it to the gateway based on the exception of a separate PI tag (referred to as a “source” tag). When the value of this source tag changes, it is sent both to the gateway and to the output tag itself. This keeps a record of data that was sent to the gateway. For more information about setting up an output tag, see the SourceTagheading of the PI Point Configurationsection on page39. If a tag is defined to be an output tag, its settings override any settings that apply to input tags.