Modbus Ethernet for NT
Interface to the PI System
Version 3.27.0.5
Rev C
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 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_ModbusE.doc
Ó 1997-2005 OSIsoft, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
Table of Contents
Introduction 1
Supported Features 1
Principles of Operation 3
Installation Checklist 5
Interface Installation 7
Interface Directories 7
The PIHOME Directory Tree 7
Interface Installation Directory 7
Interface Installation Procedure 8
Installing the Interface as an NT Service 8
Installing the Interface Service with PI-ICU 8
Installing the Interface Service Manually 10
Digital States 13
PointSource 15
PI Point Configuration 17
Point Attributes 17
Tag 17
PointSource 17
PointType 17
Location1 17
Location2 17
Location3 18
Location4 21
Location5 22
InstrumentTag 22
ExDesc 22
Scan 23
SourceTag 23
SquareRoot 24
Zero 25
Span 25
Convers 26
Shutdown 26
Input Tag Configuration 26
Output Tag Configuration 27
String Tag Configuration Example 30
Order of Data Pre/Post Processing 30
Performance Point Configuration 31
Configuring Performance Points with PI-ICU (NT-Intel) 31
Configuring Performance Points Manually 32
I/O Rate Tag Configuration 35
Monitoring I/O Rates on the Interface Node 35
Configuring I/O Rate Tags with PI-ICU (NT-Intel) 35
Configuring I/O Rate Tags Manually 36
Configuring the PI Point on the PI Server 36
Configuration on the Interface Node 37
Startup Command File 39
Configuring the Interface with PI-ICU 39
modbusE Interface Tab 41
Command-line Parameters 45
Sample ModbusE.bat File 51
Interface Node Clock 53
Security 55
Starting / Stopping the Interface 57
Starting Interface as a Service 57
Stopping Interface Running as a Service 57
Buffering 59
Configuring Buffering with PI-ICU (NT-Intel) 59
Configuring Buffering Manually 63
Example piclient.ini File 64
Appendix A: Error and Informational Messages 65
Message Logs 65
System Errors and PI Errors 65
Appendix B: Data Access Table 67
Appendix C: Modbus Message Packets 69
Function Codes 1 - 4 69
Message Packet Sent to PLC 69
Message Packet Returned by PLC 69
Function Codes 5 - 6 69
Message Packet Sent to PLC (Except for Data Type 4) 69
Message Packet Sent to PLC (Data Type 4) 70
Message Packet Returned by PLC 70
Function Code 16 70
Message Packet Sent to PLC 70
Message Packet Returned by PLC 70
Appendix D: Floating Point Representation 71
Data Type 4, Floating Point 72
Data Type 5, Floating Point 72
Data Type 6, Floating Point 72
Data Type 7, Binary Data, 4-byte Integer, Floating Points as 4-byte Integers 72
Data Type 8, Siemens Floating Point 73
Data Type 9 73
Function Code 65 73
Appendix E: PLC Notes 75
Appendix F: Simulators 77
Appendix G: Differences between Versions 2.x and 3.x of the Interface 79
Appendix H: PLC Exception Responses 81
Revision History 83
Introduction
This manual is a description of the Modbus Ethernet Interface to the PI System for Windows NT, PI-ModbusE. The interface can be run either on a PI 3 server node or on a PI Interface node that communicates to either a PI 2 or PI 3 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 / NTI (4, 2000, XP, 2003)
APS Connector / No
Point Builder Utility / No
PI-ICU Control / Yes
PI Point Types / PI 2: real / digital / integer
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
Maximum Point Count / Unlimited
Uses PI-SDK / Yes
PINet to PI 3 String Support / N/A
* Source of Timestamps / PI
History Recovery / No
Failover / No
* UniInt-Based / Yes
Vendor Software Required on PI-API / PINet Node / No
Vendor Software Required on Foreign Device / No
Vendor Hardware Required / No
Additional PI Software Included with Interface / No
* See below for further explanation.
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 our developers, and is integrated into many interfaces, such as the PI-ModbusE 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.
Principles of Operation
For proper interface operation, the user must configure input points (input tags) and/or output points (output tags) on a PI2 or PI3 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 Scan attribute 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 OVER RANGE 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.
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps you get the PI-ModbusE 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. Install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API)
2. Verify that PI-API has been installed.
3. Install the interface.
4. Ping the Modbus node from the PI Interface node to verify the connection between the two.
5. Double-check: that the PLC is in RTU mode, NOT ASCII mode.
6. Define digital states for all digital points.
7. Choose a point source. If PI 2 home node, create the point source.
8. 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.
9. Configure performance points.
10. Configure I/O Rate tag.
11. Configure the interface using the PI-ICU utility or edit startup command file manually. It is recommended to use PI-ICU whenever possible.
12. Set interface node clock.
13. Set up security.
14. Start the interface without buffering.
15. Verify data.
16. Stop interface, start buffering, start interface.
Interface Installation
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 PIAPImanual). 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 interfaces as manual services that are launched by site-specific command files when the PI Server is started. Interfaces that are started as manual services are also stopped in conjunction with the PI Server by site-specific command files. 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.
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 WinNT directory. A typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=c:\Program Files\PIPC
The above lines define the c:\Program Files\PIPC directory as the root of the PIHOME directory. 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-ModbusE interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000. 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.
Installing the Interface as an NT Service
The PI-ModbusE interface service can be created, preferably, with the PI-Interface Configuration Utility, or can be created manually.
Installing the Interface Service with PI-ICU
The PI-Interface Configuration Utility provides a user interface for creating, editing, and deleting the interface service. The screen looks similar to this: