Modbus Ethernet for Windows Interface to the PI System

Modbus Ethernet for Windows
Interface to the PI System

Version 3.28.0.0

How to Contact Us

OSIsoft, Inc.
777 Davis St., Suite 250
San Leandro, CA94577USA
Telephone
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)

Houston, TX
Johnson City, TN
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
Seattle, WA
Yardley, PA / Worldwide Offices
OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSI Software Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
OSIsoft, Inc. 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
Sales Outlets and Distributors

Brazil
Middle East/North Africa
Republic of South Africa
Russia/Central Asia

South America/Caribbean
Southeast Asia
South Korea
Taiwan

OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party’s products or any affiliation with such party of any kind.
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
Unpublished – rights reserved under the copyright laws of the United States.
© 1998-2007 OSIsoft, Inc.PI_ModbusE.doc

Table of Contents

Introduction

Supported Features

Diagram of Hardware Connection

Principles of Operation

Installation Checklist

Interface Installation on Windows

Naming Conventions and Requirements

Interface Directories

The PIHOME Directory Tree

Interface Installation Directory

Interface Installation Procedure

Installing the Interface as a Windows Service

Installing the Interface Service with PI ICU

Installing the Interface Service Manually

Digital States

PointSource

PI Point Configuration

Point Attributes

Tag

PointSource

PointType

Location1

Location2

Location3

Location4

Location5

InstrumentTag

ExDesc

Scan

Shutdown

SourceTag

SquareRoot

Zero

Span

Convers

Input Tag Configuration

Output Tag Configuration

String Tag Configuration Example

Order of Data Pre/Post Processing

Performance Point Configuration

Configuring Performance Points with PI ICU (Windows)

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 (Windows)

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

modbusE Interface Tab

Command-line Parameters

Sample ModbusE.bat File

Interface Node Clock

Security

Windows

Starting / Stopping the Interface

Starting Interface as a Service

Stopping Interface Running as a Service

Buffering

Configuring Buffering with PI ICU (Windows)

Configuring Buffering Manually

Example piclient.ini File

Appendix A: Error and Informational Messages

Message Logs

System Errors and PI Errors

Appendix B: Data Access Table

Appendix C: Modbus Message Packets

Function Codes 1 - 4

Message Packet Sent to PLC

Message Packet Returned by PLC

Function Codes 5 - 6

Message Packet Sent to PLC (Except for Data Type 4)

Message Packet Sent to PLC (Data Type 4)

Message Packet Returned by PLC

Function Code 16

Message Packet Sent to PLC

Message Packet Returned by PLC

Appendix D: Floating Point Representation

Data Type 4, Floating Point

Data Type 5, Floating Point

Data Type 6, Floating Point

Data Type 7, Binary Data, 4-byte Integer, Floating Points as 4-byte Integers

Data Type 8, Siemens Floating Point

Data Type 9

Function Code 65

Appendix E: PLC Notes

Appendix F: Simulators

Appendix G: Differences between Versions 2.x and 3.x of the Interface

Appendix H: PLC Exception Responses

Revision History

Modbus Ethernet for Windows Interface to the PI System1

Introduction

This manual is a description of the Modbus Ethernet Interface to the PI System for Windows, PI ModbusE. The interface can be run either on a PI 3 server node or on a PI Interface node that communicates to a PI server. Only Modbus communication across an Ethernet network is supported. The currently supported PLC’s are listed in Appendix C.

The interface serves as a Master in a Master-Slave relationship. There is a maximum limitation of ninety-nine (99) concurrent implementations of the interface. Operating system performance may be affected when running multiple copies of the interface on a single PC.

The interface is designed to read data from a PLC on a periodic or event basis and to send output data (commands to the PLC) on an event basis. The Modbus Interface attempts to optimize scanning performance by grouping input tags with the same scan rate, PLC destination node, and function code.

Note: This interface does not support Modbus serial-based communication or Modbus Plus communication. The versioning for this interface began at version 3.0. The previous interface, version 2.x, does support Modbus serial-based communication and Modbus Plus Communication. Version 3.x only supports Modbus Ethernet.

Supported Features

Feature / Support
Part Number / PI-IN-MO-EPLC-NTI
*Platforms / Windows (NT, 2000, XP, 2003)
APS Connector / No
Point Builder Utility / No
PI ICU Control / Yes
PI Point Types / PI 3: float16 / float32 / float64 / digital / int16 / int32 / string
Sub-second Timestamps / Yes
Sub-second Scan Classes / Yes
Automatically Incorporates PIPoint Attribute Changes / Yes
Exception Reporting / Yes
Outputs from PI / Yes
Inputs to PI: Scan-based / Unsolicited / Event Tags / Scan-based
Supports Questionable Bit / No
Supports Multi-character PointSource / Yes
Maximum Point Count / Unlimited
*Uses PI SDK / Yes
PINet String Support / N/A
* Source of Timestamps / PI
History Recovery / No
* UniInt-Based
Disconnected Startup
SetDeviceStatus / Yes
Yes
Yes
Failover / No
Vendor Software Required on PI Interface Node / No
Vendor Software Required on Foreign Device / No
Vendor Hardware Required / No
Additional PI Software Included with Interface / No
Device Point Types / Not Applicable
Serial-Based Interface / No

* See below for further explanation.

Platforms

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

Uses PI SDK

The PI SDK and the PI API are bundled together and must be installed on each PI Interface node. Under most circumstances, this interface does not specifically make PI SDK calls. However, if the version of the PI API on the interface node is less than version 1.6 or if the version of the PI Server node is earlier than 3.4.370.52, then there may be a need to enable the PI SDK by specifying the /pisdk=1 flag on the command line. Enabling the PI SDK is necessary only if you run into limitations with the length of the extended descriptor or instrument tag PI Point attributes.

Source of Timestamps

All values that are written to the snapshot or archive use the system time from the PI home node.

UniInt-Based

UniInt 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 this interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of OSIsoft’s interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniIntsupplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.

The UniInt End User Document is a supplement to this manual.

SetDeviceStatus

The PI Modbus Ethernet interface supports UniInt device status tags. The device status Health tag has the string “[UI_DEVSTAT]” in the extended descriptor (Exdesc) PI Point Attribute. Please refer to the UniInt Interface User Manual.doc file for more information on how to configure health points. Alternatively, Health tags can be configured with the PI Interface Configuration Utility.

Device status tags can be configured to monitor the status of the devices to which the interface connects. Strings of the following form can be written to the device status tag. Note that the “5 | |” at the beginning of each error string is for internal use for an application that parses this string.

“Good” – This means that the interface is able to connect to all devices for the given tag configuration of the interface. A value of “Good” does not mean that all tags are receiving good values, but it is a good indication that there are no hardware or network problems.
“1 | Starting” – The interface will remain in this status until it has successfully collected data from its first scan. Interfaces that collect data infrequently may stay in this status for a long time.
"5 | |192.168.9.77 DISCONNECTED" – This string means that the TCP/IP connection to 192.168.9.77 is not established. The connection may be lost to an IP Address if there are network problems (e.g. a bad switch in the network). This error could also be indicative of a tag configuration problem. For example, a tag could be configured with an invalid IP Address. However, once the tags have been configured properly, error strings written to this tag are a good indication of network problems. If communication is lost to multiple IP addresses, then the other problematic statuses will be listed in the error string as well, unless the error string gets longer than 200 bytes (see below).
"5 | | 1 DeviceIN EXCEPTION" – This string means thatEXCEPTION response 4, 10, or 11 has been returned from a device or gateway (see Appendix H for a list of possible exception responses). The connection to the IP Addressassociated with the device is valid, but the target device is either in severe error, unreachable, or unresponsive for some reason. You must look in the pipc.log file to determine the particular exception response and to determine the particular device and IP Address that are affected. If there are disconnected IP Addresses as well as devices in exception, the “in exception” error string will be appended to the “disconnected” error string unless the resultant error string is longer than 200 bytes (see below).
“5 | | 6 IP Addresses DISCONNECTED or with devices IN EXCEPTION”. An error string of this form is sent if the error string gets longer than 200 bytes. The error string only reports the number of IP Addresses that are either disconnected or have associated devices that are returning EXCEPTION response 4, 10, or 11. Detailed error information must be retrieved from the pipc.log file.

Diagram of Hardware Connection

The following diagram shows the PI System and the Modbus Ethernet PLCs to be on the same network. There is not need for the PI System and the Modbus Ethernet PLCs to be on the same network.

Modbus Ethernet for Windows Interface to the PI System1

Principles of Operation

For proper interface operation, the user must configure input points (input tags) and/or output points (output tags) on the PI server. Input tags are used to receive data from PLC nodes. Data are received either at a given frequency or after a value is sent to a “trigger” tag. Output tags are used to send commands to a PLC. A command is sent to a PLC after a value is sent to a “source” tag or after a value is sent to the output tag itself, depending on the configuration of the output tag. All values that are written to the snapshot or archive use the system time from the PI home node. If a communication error occurs while attempting to read data from a PLC, the interface will attempt to re-establish communication until it is successful.

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 Scanattribute of any point on the point list is set to zero, the point is removed from the point list. The point is added once again after the Scan attribute is turned back on. If neither a fixed scan rate nor a valid trigger tag is found for a given point, the point will not be added to the list.

The interface checks whether coil addresses and register addresses are within a default range. At the user’s discretion, these ranges can be adjusted in an optional Data Access Table. See the section called “Data Access Table” for more information.

The interface is designed to optimize data transfer and minimize communication traffic by collecting input data into groups. Inputs points that are configured with the same function code, scan rate, and PLC destination node are grouped together. When the amount of data that is requested for a given group exceeds the maximum data transfer size (100 byte maximum for inputs or coils, 200 byte maximum for registers) a new group is begun. The proper use of PLC memory can greatly enhance the efficiency and overall data throughput of the interface.

Whenever a PI Point of type integer or real (float) receives a value that is out of the acceptable range for the PI Point, then OVERRANGE or UNDER RANGE is written to the PI point. Whenever a PI Point of type digital receives a value that is out of range, INP OUTRANGE is written to the PI Point.

Modbus Ethernet for Windows 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 PI ModbusE interface running. If not familiar with PI interfaces, return to this section after reading the rest of the manual in detail.

Install the PI Interface Configuration Utility (which installs PI SDK and PI API)
Verify that PI API has been installed.
Install the interface.
Ping the Modbus node from the PI Interface node to verify the connection between the two.
Double-check:that the PLC is in RTU mode, NOT ASCII mode.
Define digital states for all digital points.
Choose a point source.
Configure PI points.
Location1 is the interface instance.
Location2 is the destination index.
Location3 = (Data Type * 100) + function code
Location4 is the scan class.
Location5 is the offset.
ExDesc is the bit mask.
InstrumentTag is the IP address of the destination node.
Configure performance points.
Configure I/O Rate tag.
Configure the interface using the PI ICU utility or edit startup command file manually. It is recommended to use PI ICU whenever possible.
Set interface node clock.
Set up security.
Start the interface without buffering.
Verify data.
Stop interface, start buffering, start interface.

Modbus Ethernet for Windows Interface to the PI System1

Interface Installation on Windows

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

After the interface has been installed and tested, Bufserv should be enabled on the PI Interface Node (once again, see the PI API manual). Bufserv is distributed with the PI API. It is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when communication to the PI Server is lost. Communication will be lost when there are network problems or when the PI Server is shut down for maintenance, upgrades, backups, or unexpected failures.

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 Bufserv 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. See the UniInt End User Document for special procedural information.

Naming Conventions and Requirements

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

When Configuring the Interface Manually

When configuring the interface manually it is customary for the user to rename the executable and the startup command file when multiple copies of the interface are run. For example, modbus1.exe and modbus1.bat would typically be used for interface number 1, modbus2.exe and modbus2.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

The PIHOME Directory Tree

The PIHOME directory tree is defined by the PIHOME entry in the pipc.iniconfiguration file. This pipc.ini file is an ASCII text file, which is located in the %windir%directory. A typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=c:\Program Files\PIPC
The above lines define the \PIPC directory as the root of the PIHOME directory on the C: drive. OSIsoft recommends using the \pipc as the root directory name. The PIHOMEdirectory does not need to be on the C: drive.

Interface Installation Directory

By default, the installation kit will install the modbus.exe executable in the following directory.

PIHOME\Interfaces\ModbusE\

Interface Installation Procedure

The PI ModbusEInterface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000 and greater systems. When running on Windows NT 4.0 systems, the PI ModbusE setup program will install the Windows Installer itself if necessary. To install, run the ModbusE_x.x.x.x.exe installation kit.