Modbus Ethernet - OSIsoft
Modbus Ethernet for Windows
Interface to the PI System
Version 3.27.0.6
Revision D
How to Contact Us
|OSIsoft, Inc. |Worldwide Offices |
|777 Davis St., Suite 250 |OSIsoft Australia |
|San Leandro, CA 94577 USA |Perth, Australia |
| |Auckland, New Zealand |
|Telephone |OSI Software GmbH |
|(01) 510-297-5800 (main phone) |Altenstadt, Germany |
|(01) 510-357-8136 (fax) |OSI Software Asia Pte Ltd. |
|(01) 510-297-5828 (support phone) |Singapore |
| |OSIsoft Canada ULC |
|techsupport@ |Montreal, Canada |
| |OSIsoft, Inc. Representative Office |
|Houston, TX |Shanghai, People’s Republic of China |
|Johnson City, TN |OSIsoft Japan KK |
|Mayfield Heights, OH |Tokyo, Japan |
|Phoenix, AZ |OSIsoft Mexico S. De R.L. De C.V. |
|Savannah, GA |Mexico City, Mexico |
|Seattle, WA | |
|Yardley, PA | |
|Sales Outlets and Distributors |
|Brazil |South America/Caribbean |
|Middle East/North Africa |Southeast Asia |
|Republic of South Africa |South Korea |
|Russia/Central Asia |Taiwan |
| |
|WWW. |
|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-2006 OSIsoft, Inc. |
|PI_ModbusE.doc |
Table of Contents
Introduction 1
Supported Features 1
Diagram of Hardware Connection 3
Principles of Operation 5
Installation Checklist 7
Interface Installation on Windows 9
Naming Conventions and Requirements 9
Interface Directories 10
The PIHOME Directory Tree 10
Interface Installation Directory 10
Interface Installation Procedure 10
Installing the Interface as a Windows Service 10
Installing the Interface Service with PI ICU 11
Installing the Interface Service Manually 13
Digital States 15
PointSource 17
PI Point Configuration 19
Point Attributes 19
Tag 19
PointSource 19
PointType 19
Location1 19
Location2 20
Location3 20
Location4 24
Location5 24
InstrumentTag 24
ExDesc 25
Scan 27
Shutdown 27
SourceTag 28
SquareRoot 28
Zero 29
Span 30
Convers 30
Input Tag Configuration 30
Output Tag Configuration 30
String Tag Configuration Example 34
Order of Data Pre/Post Processing 34
Performance Point Configuration 35
Configuring Performance Points with PI ICU (Windows-Intel) 35
Configuring Performance Points Manually 36
I/O Rate Tag Configuration 39
Monitoring I/O Rates on the Interface Node 39
Configuring I/O Rate Tags with PI ICU (NT-Intel) 39
Configuring I/O Rate Tags Manually 40
Configuring the PI Point on the PI Server 41
Configuration on the Interface Node 41
Startup Command File 43
Configuring the Interface with PI ICU 43
modbusE Interface Tab 46
Command-line Parameters 49
Sample ModbusE.bat File 55
Interface Node Clock 57
Security 59
Windows 59
Starting / Stopping the Interface 61
Starting Interface as a Service 61
Stopping Interface Running as a Service 61
Buffering 63
Configuring Buffering with PI ICU (Windows-Intel) 63
Configuring Buffering Manually 67
Example piclient.ini File 68
Appendix A: Error and Informational Messages 69
Message Logs 69
System Errors and PI Errors 69
Appendix B: Data Access Table 71
Appendix C: Modbus Message Packets 73
Function Codes 1 - 4 73
Message Packet Sent to PLC 73
Message Packet Returned by PLC 73
Function Codes 5 - 6 73
Message Packet Sent to PLC (Except for Data Type 4) 73
Message Packet Sent to PLC (Data Type 4) 74
Message Packet Returned by PLC 74
Function Code 16 74
Message Packet Sent to PLC 74
Message Packet Returned by PLC 74
Appendix D: Floating Point Representation 75
Data Type 4, Floating Point 76
Data Type 5, Floating Point 76
Data Type 6, Floating Point 76
Data Type 7, Binary Data, 4-byte Integer, Floating Points as 4-byte Integers 76
Data Type 8, Siemens Floating Point 77
Data Type 9 77
Function Code 65 77
Appendix E: PLC Notes 79
Appendix F: Simulators 81
Appendix G: Differences between Versions 2.x and 3.x of the Interface 83
Appendix H : PLC Exception Responses 85
Revision History 87
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 |NTI (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 PI Point Attribute |Yes |
|Changes | |
|Exception Reporting |Yes |
|Outputs from PI |Yes |
|Inputs to PI: Scan-based / Unsolicited / Event Tags|Scan-based |
|Maximum Point Count |Unlimited |
|Supports Questionable Bit |No |
|Supports Multi-character PointSource |Yes |
|Uses PI-SDK |No |
|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-Interface 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.
Platforms
The Interface is designed to run on the above mentioned Microsoft Windows operating systems and greater.
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 UniInt-supplied 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.
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.
[pic]
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 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 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.
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.
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 on Windows
OSIsoft recommends that interfaces be installed on PI Interface Nodes instead of directly on the PI Server node. A PI Interface Node is any node other than the PI Server node where the PI Application Programming Interface (PI-API) has been installed (see the PI-API manual). With this approach, the PI Server need not compete with interfaces for the machine’s resources. The primary function of the PI Server 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.ini configuration 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:\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 PIHOME directory 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 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.
Installing the Interface as a Windows 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:
[pic]
Service Configuration
Service name
The Service name box shows the name of the current interface service. This service name is obtained from the interface executable.
ID
This is the service id used to distinguish multiple instances of the same interface using the same executable.
Display name
The Display Name text box shows the current Display Name of the interface service. If there is currently no service for the selected interface, the default Display Name is the service name with a “PI-” prefix. Users may specify a different Display Name. OSIsoft suggests that the prefix “PI-” be appended to the beginning of the interface to indicate that the service is part of the OSIsoft suite of products.
Log on as
The Log on as text box shows the current “Log on as” Windows User Account of the interface service. If the service is configured to use the Local System account, the Log on as text box will show “LocalSystem”. Users may specify a different Windows User account for the service to use.
Password
If a Windows User account is entered in the Log on as text box, then a password must be provided in the Password text box, unless the account requires no password.
Confirm Password
If a password is entered in the Password text box, then it must be confirmed in the Confirm Password text box.
Startup Type
The Startup Type indicates whether the interface service will start automatically or need to be started manually on reboot.
• If the Auto option is selected, the service will be installed to start automatically when the machine reboots.
• If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.
• If the Disabled option is selected, the service will not start at all.
Generally, interface services are set to start automatically.
Dependencies
The Installed services list is a list of the services currently installed on this machine. Services upon which this Interface is dependant should be moved into the Dependencies list using the [pic] button. For example, if API Buffering is running, then “bufserv” should be selected from the list at the right and added to the list on the left. Often interface services also depend on a vendor program. To remove a service from the list of dependencies, use the [pic] button, and the service name will be removed from the “Dependencies” list.
When the PI Interface is started (as a service), the services listed in the dependency list will be verified as running (or an attempt will be made to start them). If the dependent service(s) cannot be started for any reason, then the PI interface service will not run.
Note: Please see the PI Log and Operating System Event Logger for messages that may indicate the cause for any server not running as expected.
[pic] - Add Button
To add a dependency from the list of Installed services, select the dependency name, and click the Add button.
[pic] - Remove Button
To remove a selected dependency, highlight the service name in the Dependencies list, and click the Remove button.
The full name of the service selected in the Installed services list is displayed below the Installed services list box.
Create
The Create button adds the displayed service with the specified Dependencies and with the specified Startup Type.
Remove
The Remove button removes the displayed service. If the service is not currently installed, or if the service is currently running, this button will be grayed out.
Start or Stop Service
To Start or Stop an interface service, use the Start button [pic] and a Stop button [pic] on the ICU toolbar. If this interface service is not currently installed, these buttons will remain grayed out until the service is added. If this interface service is running, the Stop button is available. If this service is not running, the Start button is available.
The status of the Interface service is indicated in the lower portion of the PI ICU dialog.
[pic]
Installing the Interface Service Manually
Help for installing the interface as a service is available at any time with the command:
modbusE.exe –help
The following procedure will create an interface service that will read its command-line parameters from a command file named modbusE.bat, where is specified using the -serviceid command-line parameter. The modbusE.bat file must be in the same directory as the interface executable. If -serviceid is not specified, then the service will read its command-line parameters from modbusE.bat.
The -serviceid command-line parameter should not be confused with the /id command-line parameter. Unlike the /id command line parameter, the -serviceid command-line parameter should never be specified in the startup command file of the interface. The -serviceid parameter is only used for installing a service. A service that is installed with a particular serviceid will get its command-line parameters from the modbusE.bat file.
The /id command-line parameter determines which points are loaded by the interface according to the location1 PI Point Attribute. It is not necessary for identifiers specified by the -serviceid and /id parameters to match.
The PI ICU installs multiple services for a single executable with the -serviceid approach. Another valid approach to creating multiple interface services is to rename the Modbus Ethernet executable multiple times and to install the renamed executables as a service multiple times. With the latter approach the -serviceid parameter is not needed.
To install a service from a command window, go to the directory where the modbusE.exe executable is located. Next, consult the following table to determine the appropriate service installation command.
|Interface depends on Bufserv |
|PI-SDK not enabled for interface (/pisdk=0) |
|Manual service |ModbusE.exe –install –depend “tcpip bufserv” –serviceid |
| |-display “PI ModbusE Interface ” |
|*Automatic service |ModbusE.exe –install –auto –depend “tcpip bufserv” –serviceid |
| |-display “PI ModbusE Interface ” |
|Interface does not depend on Bufserv |
|PI-SDK not enabled for interface (/pisdk=0) |
|Manual service |ModbusE.exe –install –depend tcpip –serviceid |
| |-display “PI ModbusE Interface ” |
|*Automatic service |ModbusE.exe –install –auto –depend tcpip –serviceid |
| |-display “PI ModbusE Interface ” |
|Interface does depends on Bufserv |
|PI-SDK enabled for interface (/pisdk=1) |
|Manual service |ModbusE.exe –install –depend “pinetmgr bufserv” –serviceid |
| |-display “PI ModbusE Interface ” |
|*Automatic service |ModbusE.exe –install -auto –depend “pinetmgr bufserv” |
| |–serviceid -display “PI ModbusE Interface ” |
|Interface does not depend on Bufserv |
|PI-SDK enabled for interface (/pisdk=1) |
|Manual service |ModbusE.exe –install –depend pinetmgr –serviceid |
| |-display “PI ModbusE Interface ” |
|*Automatic service |ModbusE.exe –install -auto –depend bufserv |
| |–serviceid -display “PI ModbusE Interface ” |
*When specifying service id, the user must include an id number. It is suggested that this number correspond to the interface id (/id) or (/if) parameter found in the interface .bat file.
Check the Microsoft Windows NT services control panel to verify that the service was added successfully. One can use the services control panel at any time to change the interface from an automatic service to a manual service or vice versa.
Digital States
For more information regarding Digital States, refer to the Data Archive Manuals.
Digital State Sets
PI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Server manuals.
An interface point that contains discrete data can be stored in PI as a digital tag. A Digital tag associates discrete data with a digital state set, as specified by the user.
System Digital State Set
Similar to digital state sets is the system digital state set. This set is used for all tags, regardless of type to indicate the state of a tag at a particular time. For example, if the interface receives bad data from an interface point, it writes the system digital state bad input to PI instead of a value. The system digital state set has many unused states that can be used by the interface and other PI clients.
PointSource
The PointSource is a unique, single or multi-character string that is used to identify the PI point as a point that belongs to a particular interface. For example, the string Boiler1 may be used to identify points that belong to the MyInt Interface. To implement this, the PointSource attribute would be set to Boiler1 for every PI Point that is configured for the MyInt Interface. Then, if /ps=Boiler1 is used on the startup-command line of the MyInt Interface, the Interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of Boiler1. Before an interface loads a point, the interface usually performs further checks by examining additional PI point attributes to determine whether a particular point is valid for the interface. For additional information, see the /ps parameter.
Case-sensitivity for PointSource Attributes
If the interface is running on a PINet node and the Server node is a PI 3 system, use a capital letter (or a case-insensitive character such as a number, a question mark, etc.) for the PointSource attribute when defining points. For all other scenarios, one does not need to be careful with the case of the PointSource.
In all cases, the point source character that is supplied with the /ps command-line parameter is not case sensitive. That is, /ps=M and /ps=m are equivalent. One only needs to be careful with the case of the PointSource during point definition, and only if the interface will be running on a PINet node communicating to a PI 3 Server.
Reserved Point Sources
Several subsystems and applications that ship with PI are associated with default PointSource characters. The Totalizer Subsystem uses the PointSource character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Do not use these PointSource characters or change the default point source characters for these applications. Also, if a PointSource character is not explicitly defined when creating a PI point; the point is assigned a default PointSource character of Lab (PI 3). Therefore, it would be confusing to use Lab as the PointSource character for an interface.
Note: Do not use a point source character that is already associated with another interface program. However it is acceptable to use the same point source for multiple instances of an interface.
PI Point Configuration
The PI point is the basic building block for controlling data flow to and from the PI Data Archive. A single point is configured for each measurement value that needs to be archived. Use the point attributes below to define what data to transfer.
Point Attributes
PI points must be configured in order to transmit data to or from a PLC. Use the point attributes below to define the PI Point configuration for the Interface, including specifically what data to transfer.
Tag
A Tag is a label or name for a point. Any tag name can be used in accordance to the normal PI point naming conventions.
Length
The length of the Tag field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.
|Software |Version |Maximum Length |
|This Interface |Current |1023 |
|PI API |Below 1.6 |255 |
|PI API |1.6 |1023 |
|PI Server |Below 3.4.370.x |255 |
|PI Server |3.4.370.x or higher |1023 |
PointSource
The PointSource is a single, unique character that is used to identify the PI point as a point that belongs to a particular interface. For additional information, see the /ps command-line parameter and the “Point Source” section.
PointType
The following point types are supported: float16, float32, int16, int32, digital, and string. String tags are supported only for input PI Tags.
Location1
Location1 indicates to which copy of the interface the point belongs. The value of this attribute must match the /id startup parameter.
Valid interface numbers are integer values 1 to 99, inclusive.
Location2
The Location2 parameter corresponds to the destination index. The destination index is also referred to as a unit identifier. For Quantum PLC’s the destination index (dst_idx) is described in Appendix C of the Modicon Quantum Ethernet TCP/IP Module User Guide.
The destination index does not correspond to the IP address of the PLC. Instead, the IP address is specified in the InstrumentTag attribute.
The destination index is used for intra-system routing of packets at the destination node, and it is currently not implemented for most PLCs, including Quantum PLCs. However, PLC simulators such as ModSim32 by WinTECH Software () do use the destination index number because more than one PLC simulator can run simultaneously on a single machine. That is, the IP address would be identical for two simulators that are running on the same computer and the destination index is used to determine which simulator is being addressed.
It is recommended that the destination index be specified, if it is known, to ensure forward compatibility or to allow a simulator to be used for testing.
Note: The PI ModbusE interface will connect to the PLC via the well-known port of 502.
Location3
Location3 = (Data Type * 100) + function code
Example: For function code 4 (read input register) and Data Type 2 (4-digit BCD), Location3 should be 204.
The function code refers to the corresponding Modbus function code.
The Data Type determines whether the register values in the PLC are interpreted as integers, floats, binary coded decimals, etc.
Note that function code 65 is non-standard Modbus. There is no data type that is associated with function code 65. Hence, location3 should be assigned a value of 65 when this function type is required.
|Data Type |Comments |
|1 |16 bit Integer |
| |For real PI points, the 16-bit register is interpreted as a signed integer (-32768 to 32767). |
| |For integer PI Points, the 16-bit register is interpreted as an unsigned integer (0 to 65535). |
| |Additional notes: |
| |Integer points in PI 2 and int16 points in PI 3 can take values between 0 and 32767. As |
| |mentioned above, however, the 16-bit register value is interpreted as an unsigned integer between|
| |0 and 65535 for integer type PI points and data type 1. If a value greater than 32767 is sent to|
| |an integer point in PI 2 or to an int16 in PI 3, OVER RANGE will be written to the point instead.|
| |Scaled real points in PI 2 and float16 points in PI 2 can take values between 0 and 32767. As |
| |mentioned above, however, the 16-bit register value is interpreted as a signed integer between |
| |–32768 and 32767 for a real type PI point and data type 1. If a value that is less than 0 is |
| |sent to a scaled real point in PI 2 or to a float16 point in PI 3, UNDER RANGE will be written to|
| |the point instead. |
| |Full-precision real points in PI 2 are true 32-bit floats. Values between –32768 and 32767 can |
| |be sent to PI using full precision PI 2 real points and data type 1. There should be no problems|
| |with UNDER RANGE or OVER RANGE with full precision real points in PI 2. |
| |The 16-bit register value for data type 1 is interpreted as an unsigned integer between 0 and |
| |65535 for int32 points in PI 3. There are no problems with UNDER RANGE or OVER RANGE for int32 |
| |points in PI 3. |
| |The 16-bit register value for data type 1 is interpreted as an unsigned integer between –32768 |
| |and 32767 for float32 points in PI 3. There are no problems with UNDER RANGE or OVER RANGE for |
| |float32 points in PI 3. |
|2 |4-Digit Binary-Coded Decimal (BCD) |
| |For input points, the 16-bit register is converted from a BCD to an integer. For output points, |
| |the value of the PI point is converted from an integer to a BCD before it is written to the |
| |register. |
| |BCD representation of integer values between 0 and 9999 are supported. If a negative value is |
| |written to a source tag of an output point, UNDER RANGE is written to the output point. If a |
| |value greater than 9999 is written to the source tag of an output point, then OVER RANGE is |
| |written to the output point. |
| |Example: |
| |The integer 1925 is represented as a BCD by the hexadecimal number 0x1925 (or by the integer |
| |6437). Each byte of the BCD represents one digit of the integer. |
|3 |Log Base 2 |
| |The range of values that can be written to an output point are between 0 and 15, inclusive. |
| |There is no range checking for input points. |
| |Example: |
| |If a value of 5 is written to an output point, then 25 or 32 is written to the register. If 32 |
| |is read from a register into an input point, it is converted to a value of 5 before it is stored |
| |in the input point. |
|4 |Floating Point, 32 bit (Appendix B has more information on floating points) |
| |Used with function codes 3, 4, and 6 only. |
| |Values stored in the PLC are interpreted as a standard IEEE 4-byte float. For PI 2, the PI point|
| |should be configured as a full precision real. For PI 3, the PI point should be configured as a |
| |float32. |
| |A PLC that understands data type 4, interprets function code 3, 4, and 6 in a nonstandard |
| |fashion. The PLC maps a single register to two different registers so that the single register |
| |can effectively store four bytes of information instead of two. |
|5 |Floating Point (Appendix B has more information on floating points) |
| |Used with function codes 3, 4, and 6 only. |
| |Values stored in the PLC are interpreted as a standard IEEE 4-byte float. For PI 2, the PI point|
| |should be configured as a full precision real. For PI 3, the PI point should be configured as a |
| |float32. |
| |A PLC that understands data type 5, interprets function code 3, 4, and 6 in a nonstandard |
| |fashion. When data from register 5 is requested, for example, data from both registers 5 and 6 |
| |is returned. |
|6 |Floating Point (Appendix B has more information on floating points) |
| |Used with function codes 3, 4, and 6 only. |
| |Values stored in the PLC are interpreted as a standard IEEE 4-byte float. For PI 2, the PI point|
| |should be configured as a full precision real. For PI 3, the PI point should be configured as a |
| |float32. |
| |This is the most common data type for floating points. Try this data type first. If this data |
| |type does not work, try adding the /swap6 parameter to the command line of the interface before |
| |trying a different data type. |
|7 |4-Byte Integer (Appendix B has more information on 4-byte integers). |
| |Used with function codes 3, 4, and 6 only. |
| |When data type 7 is used, the modbus interface combines the values from 2-consecuative 2-byte |
| |registers to come up with a 4-byte integer. |
| |To avoid problems with OVER RANGE and UNDER RANGE, the PI Point should be configured as a full |
| |precision real in PI 2 or as an int32 or a float32 in PI 3. See data type 1 for further |
| |information regarding the limitations of the different PI Point types. |
|8 |Siemens Floating point (see Appendix B for more information). |
| |Used with function codes 3, 4, and 6 only. |
| |Values stored in the PLC are interpreted as Siemens floating point format. This format is only |
| |required in very specialized cases. For PI 2, the PI point should be configured as a full |
| |precision real. For PI 3, the PI point should be configured as a float32. |
|9 |4-Byte Integer |
| |Used with function codes 3, 4, and 6 only. |
| |This data type is similar to data type 7 except that the registers that hold the values are true |
| |4-byte registers. Standard Modbus registers are 2-byte registers. Some hardware devices support|
| |4-byte registers. This data type is analogous to data type 4, except that the Modbus interface |
| |expects an IEEE floating point value to be stored in the 4-byte register when data type 4 is |
| |specified and the Modbus interface expects a 4-byte integer to be stored in the 4-byte register |
| |when data type 9 is specified. |
|11 |16 bit Integer |
| |Used with function codes 1, 2, 3, and 4 only. |
| |Data type 11 is identical to data type 1 except that the 16-bit register is interpreted as an |
| |unsigned integer (0 to 65535) for both integer PI Points and real PI Points. |
|12 |16-Digit Binary-Coded Decimal (BCD) (supported for input tags only) |
| |Four consecutive 2-byte registers are converted from a BCD to an integer. It is recommended that|
| |the integer be stored in a float64 tag to maximize the significant digits. Note, however, that a|
| |float64 tag only has 13 digits of precision whereas a 16-digit BCD has 16-digits of precision. |
|16 |Double precision floating point (supported for input tags only) |
| |Used with function codes 3 and 4. |
| |Values stored in the PLC are interpreted as a standard IEEE 8-byte double precision floating |
| |point values. However, the value that is actually stored in PI will be a single precision |
| |floating point value even if the PI point type is float64. For PI 2, the PI point should be |
| |configured as a full precision real. For PI 3, the PI point should be configured as a float32 or|
| |float64. |
| |When this data type is used, the Modbus interface expects to read the double from 4 consecutive |
| |2-byte registers on the PLC. Data type 16 is the 8-byte equivalent of data type 6, which is used|
| |for 4-byte IEEE floats. |
|101 to 199 |Data types 101 to 199 are reserved for string data. Data type 101 is used to read 1-byte |
| |strings; data type 102 is used to read 2-byte strings; and so on. For example to read a 5-byte |
| |string from an input register (Modbus function code 4) one would set the location3 attribute to |
| |10504 because location3 is equal to (DataType*100 + FunctionCode). |
|Function Code |Description |
|1 |Read Coil Status to input tag. Used only with Data Type 1. |
|2 |Read Input Status to input tag. Used only with Data Type 1. |
|3 |Read Holding Register to input tag. |
|4 |Read Input Register to input tag. |
|5 |Write Single Coil using output tag. Used only with Data Type 1. |
|6 |Write registers using output tag. |
| |Note: the interface will convert function code 6 to 16 when it is necessary to send floating |
| |point numbers to two consecutive registers. |
|65 |Read floating point value from 4-byte register. There is no data type associated with function |
| |code 65 because the interpretation of the register value is determined by the function code |
| |itself. |
| |See Appendix B for more information on function code 65. |
Location4
Scan-based Inputs
Location4 defines the scan class for the PI point. The scan class determines the frequency at which input points are scanned for new values. For more information, see the description of the /f parameter in the section called “Startup Command File”.
Trigger-based Inputs and Output Points
Location4 should be set to zero for these points.
Location5
Location5 is used to specify an offset to a particular coil, input status, holding register, or input register. It is important to realize that Location5 is used to specify an offset, not an absolute address. For example, if the value from holding register 40083 is to be read and the first holding register begins at 40001, specify 83 in Location5, not 40083. The correct absolute address, 40083, will be accessed as long as one specifies a function code of 3 in Location3 (for example, Location3=103).
For Modicon Hardware: function codes 1 and 5 begin at coil 1, function code 2 begins at input 1001 or 10001 or 100001, function codes 3 and 6 begin at holding register 4001 or 40001 or 400001, and function code 4 begins at input register 3001 or 30001 or 300001. For Honeywell Hardware: I/O locations range from 0 to 4095 and registers locations start at 4096.
InstrumentTag
Length
The length of the InstrumentTag field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.
|Software |Version |Maximum Length |
|This Interface |Current |1023 |
|PI API |Below 1.6 |32 |
|PI API |1.6 |1023 |
|PI Server |Below 3.4.370.x |32 |
|PI Server |3.4.370.x or higher |1023 |
The InstrumentTag attribute is used to specify the IP address of the destination node. It is specified in the form:
xxx.xxx.xxx.xxx
where xxx represents a number between 0 and 255.
The PI ModbusE interface will connect to the PLC via the well-known port of 502.
ExDesc
Length
The length of the Extended Descriptor field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.
|Software |Version |Maximum Length |
|This Interface |Current |1023 |
|PI API |Below 1.6 |80 |
|PI API |1.6 |1023 |
|PI Server |Below 3.4.370.x |80 |
|PI Server |3.4.370.x or higher |1023 |
The extended descriptor can be used to specify a “triggertag” (for input tags only), a bit mask (for input tags only), and an instrument zero (InstZero) for a PLC.
Use the following syntax for the extended descriptor:
event=triggertag, b=bitmask, z=InstZero
For example:
event=sinusoid, b=01, z=10
The triggertag, bitmask and InstZero fields must be separated by comas.
Bit Mask
The bit mask can be used only with input tags of data type 1, 7, or 9. The bit mask does not apply to output tags. The format of the bit mask is: b=uuvvwwxxyyzz
where uu, vv, ww, yy, and zz each refer to a single bit. A leading zero is required if the referenced bit is less than 10. The low-order bit is 01 and high-order bit is 16. Up to 16 bits can be referenced for a 16-bit word (data type 1) and up to 32 bits can be reference for a 32-bit word (data type 7).
The bit mask 0307120802 will map the second bit of the original word to the first bit of the new word, the eighth bit to the second bit, the twelfth bit to the third bit, etc. The high-order bits of the new word are padded with zeros if they are not specified.
Say a single 16-bit PLC register holds the state of four different thermocouples. The first 4 bits correspond to the first thermocouple; the second 4 bits correspond to the second thermocouple, etc. Four different input tags with four different bit masks could be used to read thermocouple states. The first input tag would use a bit mask of 04030201 to read the state of the first thermocouple; the second input tag would use a bit mask of 08070605 to read the state of the second thermocouple, and so on. If the sixteen bit word from the PLC was 0000 0000 0101 0111 or decimal 87, then the first thermocouple state would be interpreted as binary 0111 or decimal 7, the second thermocouple state would be interpreted as 0101 or decimal 5, etc.
For 4-byte integer values (data type 7), the bytes for these tags are frequently swapped. The bytes can be swapped with the following bitmask:
"b=1615141312111009080706050403020132313029282726252423222120191817"
InstZero
The InstZero field is described in the table under the SquareRoot attribute. The default value of InstZero is zero if it is not defined in the extended descriptor.
Performance Points
For UniInt-based interfaces, the extended descriptor is checked for the string “PERFORMANCE_POINT”. If this character string is found, UniInt treats this point as a performance point. See the section called “Performance Points.”
Trigger-based Inputs
A triggertag can be used in conjunction with an input tag. An input tag is a tag for which the function code has been set to 1, 2, 3, or 4 in Location3. By specifying a triggertag, the associated input tag is scanned after an “event” instead of being scanned at the frequency specified in Location4. See the section entitled “Input Tag Configuration” for essential details on input tags and triggertags.
For trigger-based input points, a separate trigger point must be configured. An input point is associated with a trigger point by entering a case-insensitive string in the extended descriptor (ExDesc) PI point attribute of the input point of the form:
keyword=trigger_tag_name
where keyword is replaced by “event” or “trig” and trigger_tag_name is replaced by the name of the trigger point. There should be no spaces in the string. UniInt automatically assumes that an input point is trigger-based instead of scan-based when the keyword=trigger_tag_name string is found in the extended descriptor attribute.
An input is triggered when a new value is sent to the Snapshot of the trigger point. The new value does not need to be different than the previous Snapshot value to trigger an input, but the timestamp of the new value must be greater than (more recent than) or equal to the timestamp of the previous value. This is different than the trigger mechanism for output points. For output points, the timestamp of the trigger value must be greater than (not greater than or equal to) the timestamp of the previous value.
Conditions can be placed on trigger events. Event conditions are specified in the extended descriptor as follows:
Event=‘trigger_tag_name’ event_condition
The trigger tag name must be in single quotes. For example,
Event=‘Sinuoid’ Anychange
will trigger on any event to the PI Tag sinusoid as long as the next event is different than the last event. The initial event is read from the snapshot.
The keywords in the following table can be used to specify trigger conditions.
|Event Condition |Description |
|Anychange |Trigger on any change as long as the value of the current event is different than the value of the |
| |previous event. System digital states also trigger events. For example, an event will be triggered|
| |on a value change from 0 to “Bad Input,” and an event will be triggered on a value change from “Bad |
| |Input” to 0. |
|Increment |Trigger on any increase in value. System digital states do not trigger events. For example, an |
| |event will be triggered on a value change from 0 to 1, but an event will not be triggered on a value|
| |change from “Pt Created” to 0. Likewise, an event will not be triggered on a value change from 0 to|
| |“Bad Input.” |
|Decrement |Trigger on any decrease in value. System digital states do not trigger events. For example, an |
| |event will be triggered on a value change from 1 to 0, but an event will not be triggered on a value|
| |change from “Pt Created” to 0. Likewise, an event will not be triggered on a value change from 0 to|
| |“Bad Input.” |
|Nonzero |Trigger on any non-zero value. Events are not triggered when a system digital state is written to |
| |the trigger tag. For example, an event is triggered on a value change from “Pt Created” to 1, but |
| |an event is not triggered on a value change from 1 to “Bad Input.” |
Scan
By default, the Scan attribute has a value of 1, which means that scanning is turned on for the point. Setting the scan attribute to 0 turns scanning off. If the scan attribute is 0 when the interface starts, SCAN OFF will be written to the PI point. If the scan attribute is changed from 1 to 0 while the interface is running, SCAN OFF will also be written to the PI point after the point edit is detected by the interface.
There is one other situation, which is independent of the Scan attribute, where UniInt will write SCAN OFF to a PI point. If a point that is currently loaded by the interface is edited so that the point is no longer valid for the interface, the point will be removed from the interface, and SCAN OFF will be written to the point. For example, if the PointSource of a PI point that is currently loaded by the interface is changed, the point will be removed from the interface and SCAN OFF will be written to the point.
Shutdown
The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Server manuals.
Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are independent of the SHUTDOWN events that are written by the interface when the /stopstat=Shutdown command-line parameter is specified.
SHUTDOWN events can be disabled from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, the default behavior of the PI Shutdown Subsystem can be changed to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the \PI\dat\Shutdown.dat file, as discussed in PI Server manuals.
Bufserv
It is undesirable to write shutdown events when Bufserv is being used. Bufserv is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when the Server is down for maintenance, upgrades, backups, and unexpected failures. That is, when PI is shut down, Bufserv will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface.
SourceTag
A SourceTag is used in conjunction with an output tag. An output tag is a tag for which the function code has been set to 5 or 6 in Location3. See the section entitled “Output Tag Configuration” for essential details on output tags and the SourceTag.
SquareRoot
The SquareRoot attribute is used to specify operations to be applied to input and/or output values. OPERATIONS ARE NEVER APPLIED FOR DIGITAL TAGS.
Several parameters are used for the operations, including:
|Convers |The conversion factor PI Point Attribute. |
|InstZero |The instrument zero of the PLC, which is defined in the extended descriptor. |
|Zero |The Zero PI Point Attribute. |
|Span |The Span PI Point Attribute. |
|Value |This parameter represents a value from a PLC that is sent to an input tag or a value that is |
| |sent to a PLC from an output tag (or SourceTag). The conversions below are performed on Value.|
Example: An input tag is used to read the temperature of a beaker of water. The water temperature range is between 0oC and 100oC. The range of values from the PLC is between -10000 and +10000, where -10000 corresponds to 0oC and 10000 corresponds to 100oC. To properly convert the value from the PLC to a temperature in oC, use the following settings: InstZero=-10000, Convers=20000, Zero=0, Span=100, SquareRoot=0.
The conversion that is applied depends upon the value of the SquareRoot and Convers attributes:
|Conditions: |Operation: |
|SquareRoot=0 |Input tags: |
|Convers(0 and |Value = [ (Value – InstZero)/ Convers ] * Span + Zero |
|Convers(1 |Output tags: |
| |Value = [ (Value - Zero)/Span] *Convers + InstZero |
|SquareRoot=0 |No operation performed on input or output tags: |
|Convers=0 or |Value = Value |
|Convers=1 | |
|SquareRoot=1 |Input tags: |
|Convers(0 and |Value = [ { (Value)0.5 – InstZero }/ Convers ] * Span + Zero |
|Convers(1 |Output tags: |
| |Value = {[ (Value - Zero)/Span] *Convers + InstZero}2 |
|SquareRoot=1 |Input tags and output tags: |
|Convers=0 or |Value = (Value)0.5 |
|Convers=1 | |
|SquareRoot=2 |Input tags: |
|Convers(0 or |Value = [ { (Value)2 – InstZero }/ Convers ] * Span + Zero |
|Convers(1 |Output tags: |
| |Value = { [ (Value - Zero)/Span] *Convers + InstZero }0.5 |
|SquareRoot=2 |Input tags and output tags: |
|Convers=0 or |Value = (Value)2 |
|Convers=1 or point type | |
|is digital | |
|SquareRoot=3 |For floating point input tags (i.e., type real, float16, float32) and for Location3 of |
|Convers(0 |103, 104, 106, 703, 704, 706: |
| |Value = Value/Convers |
| |For floating point output tags (i.e., type real, float16, float32) and for Location3 of |
| |103, 104, 106, 703, 704, 706: |
| |Value = Value*Convers |
| |If Location3 is not equal to 103, 104, 106, 703, 704, 706 or if the tag is of type |
| |integer (i.e., integer, int16, in32), then SquareRoot=3 is the same as SquareRoot=0. |
|SquareRoot=3 |No operation performed on input or output tags: |
|Convers=0 |Value = Value |
|SquareRoot=4 |Same as SquareRoot=0 |
|SquareRoot=5 |Input tags: |
|Convers=(0 |Value = (Value/Convers) – InstZero |
| |Output tags: |
| |Value = (Value + InstZero)*Convers |
|SquareRoot=5 |No operation performed on input or output tags: |
|Convers=0 |Value = Value |
|SquareRoot=5 |No operation performed on input or output tags: |
|Convers=0 |Value = Value |
|SquareRoot=6 |Input tags: |
|Convers=(0 |Value = (Value - InstZero)/Convers |
| |Output tags: |
| |Value = (Value*Convers) + InstZero |
|SquareRoot=6 |No operation performed on input or output tags: |
|Convers=0 |Value = Value |
Zero
The Zero attribute ideally represents the lowest possible value for an input or an output tag. The Zero attribute is not the same as the instrument zero (InstZero), which is described in the extended descriptor. Do not assign a value to the Zero attribute for PI Points of type digital. Changing the Zero attribute for a digital tag can adversely affect the configuration of the PI Point.
The interface will not throw out or alter values that are less than the Zero PI Point attribute. The interface only uses the Zero attribute to perform the conversions that are described under the SquareRoot PI Point attribute.
Span
The sum of the Zero and Span attributes ideally represents the maximum possible value for an input or an output tag. Do not assign a value to the Span attribute for PI Points of type digital. Changing the Span attribute for a digital tag can adversely affect the configuration of the PI Point.
The interface will not throw out or alter values that are outside of the range specified by the Zero and Span. The interface only uses the Zero and Span attributes to perform the conversions that are described under the SquareRoot PI Point attribute.
Convers
This attribute specifies the conversion factor. The use of the conversion factor is described under the SquareRoot PI Point attribute.
Input Tag Configuration
Input tags are used to receive data from PLC nodes. A tag is an input tag if function code 1, 2, 3, 4, or 65 is specified in Location3 (Location3 = 100*data_type + function_code). For example, if location3 is 603, then the PI Point is an input tag.
If no “triggertag” is specified in the extended descriptor (ExDesc) attribute of the input tag, then the associated PLC will be scanned at a given frequency. The frequency is specified using the Location4 point attribute in conjunction with the /f parameter on the startup command line of the interface. The input tag is said to be scan-based in this case.
If a “triggertag” is specified in the extended descriptor (ExDesc) attribute of the input tag, then the associated PLC will be scanned only when a new value is sent to the snapshot of the triggertag. The input tag is said to be event-based in this case.
Whenever a complete response fails to be received from a PLC before a configurable timeout period has expired (see the /to=x startup command-line parameter), I/O TIMEOUT will be written to the affected tags.
If a communication error occurs that is not associated with a timeout, then BAD INPUT will be written to the affected tags instead of I/O TIMEOUT.
If the Scan field of an input tag is turned off while the interface is running, SCAN OFF (digital state 238) will be written to the input tag.
There are several other digital states that can also be written to input tags. These must be handled on a case-by-case basis.
Output Tag Configuration
Output tags are used to send commands to a PLC node. A tag is an output tag if function code 5 or 6 is specified in Location3. Commands are sent to the PLC only upon an event. An event is triggered in one of two ways, depending upon the configuration of the output tag.
Configuration 1 (recommended)
In this configuration, a command is written to the PLC when an event is detected for a SourceTag. A SourceTag is associated with an output tag through the output tag’s SourceTag field. The value of the SourceTag is written to the output tag if the command is successful. The PointType of the output tag and SourceTag do not need to be the same.
Configuration 2
In this configuration, a command is written to the PLC when an event is detected for the output tag itself. This configuration is enabled if no SourceTag is defined in the output tag’s SourceTag field.
When do “Events” Occur?
An event occurs whenever a value reaches the snapshot of the SourceTag (configuration 1) or the output tag (configuration 2). The actual value of the snapshot does not need to change to trigger an event
What Commands are Sent to the PLC?
The command is determined by the Location3 value of the output tag. For example, if Location3 is set to 105, then the command to the PLC will be to force a single coil either on or off. The coil is turned on if the trigger value that is sent to the SourceTag (configuration 1) or to the output tag (configuration 2) is greater than zero. The coil is turned off if the trigger value that is sent to the SourceTag (configuration 1) or output tag (configuration 2) is equal to zero. If Location3 is set to 106, then the command is to modify the contents of a holding register. The value that is sent to the holding register is determined by the value that is sent to the SourceTag (configuration 1) or output tag (configuration 2).
Digital State Messages Sent to the Output Tag
Informative digital state messages are sent to the output tag only for configuration 1, which is why configuration 1 is recommended. If there is trouble sending a command to the PLC, then an appropriate digital state is written to the output tag. The use of output tags is demonstrated below by examples.
Example 1
Configure an output tag and a source tag to force coil number 131 on or off (function code 5). The source tag should be configured so that the on/off status of the coil can be changed using manual inputs. Assume that the interface number is 2, that the PLC node is 77, and that the PointSource for the interface is M.
Solution - Part 1, Configure the Output Tag
Call the output tag c131out. The output tag is used to specify the interface number (Location1), the PLC node (Location2), the data type and function code (Location3), and the coil number to be changed (Location5). The Location4 parameter is ignored when the SourceTag field is specified. The PointSource for the output tag corresponds to the Modbus interface, which is M in this example. The PointType of the output tag and the SourceTag are configured to be the same. The CompDev and ExcDev are set to zero for the output tag because the source tag is to be configured as a manual input point (lab data) for which the CompDev and ExcDev should also be zero. Generally, compression and exception should be turned off for manually entered points. The zero and span are set to correspond to the source tag. A TypicalValue and a SquareRoot code are configured below. We are at liberty to specify any value for these parameters (and other parameters) since no restrictions were posed in the problem statement. For a PI3 home node, the user may additionally wish to set Step=1.
|Output Tag Configuration - Example 1 |
| |PI2 Home node |PI3 Home node |
|Tag |c131out |c131out |
|PointType |scaled integer |int16 |
|Zero |0 |0 |
|Span |1 |1 |
|TypicalValue |1 |1 |
|PointSource |M |M |
|Location1 |2 |2 |
|Location2 |77 |77 |
|Location3 |105 |105 |
|Location5 |131 |131 |
|SquareRoot |0 |0 |
|SourceTag |c131src |c131src |
|CompDev |0 |0 |
|ExcDev |0 |0 |
Solution - Part 2, Configure the SourceTag
No restrictions are placed on the PointSource, but Pointsource L is appropriate for the manual inputs required in this example. The CompDev and ExcDev are set to zero, which is appropriate for manually entered points. Since the SourceTag does not receive values from an interface (in this example) the Location parameters are ignored if specified. When the source tag is set to 0, coil 131 will be turned off. When the source tag is set to any positive value, coil 131 will be turned on. The zero is set to 0 and the Span is set to 1, which is the minimum range required to turn the coil off and on.
|Source Tag Configuration - Example 1 |
| |PI2 Home node |PI3 Home node |
|Tag |c131src |c131src |
|PointType |Integer |int16 |
|Zero |0 |0 |
|Span |1 |1 |
|TypicalValue |1 |1 |
|PointSource |L |L |
|CompDev |0 |0 |
|ExcDev |0 |0 |
Example 2
Configure an output tag to force coil number 131 on or off (function code 5). Do not configure a source tag. Since no source tag is to be used, the values for the output tag must be entered manually. Assume that the interface number is 2, that the PLC node is 77, and that the PointSource for the interface is M.
Solution
The configuration is the same as in example 1 except that no source tag is specified in the configuration. When the output tag is set to 0, coil 131 will be turned off. When the output tag is set to any positive value, coil 131 will be turned on. The zero is set to 0 and the Span is set to 1, which is the minimum range required to turn the coil off and on. The PointSource must be M.
|Output Tag Configuration - Example 2 |
| |PI2 Home node |PI3 Home node |
|Tag |c131out |c131out |
|PointType |Integer |int16 |
|Zero |0 |0 |
|Span |1 |1 |
|TypicalValue |1 |1 |
|PointSource |M |M |
|Location1 |2 |2 |
|Location2 |77 |77 |
|Location3 |105 |105 |
|Location5 |131 |131 |
|SquareRoot |0 |0 |
|CompDev |0 |0 |
|ExcDev |0 |0 |
String Tag Configuration Example
Each register is 2 bytes, so each register can store 2 characters.
For example, if the register holds a value of 25185, then the low order byte of the register is 97 (0x61) and the high order byte is 98 (0x62). The ASCII character code of 97 corresponds to the letter “a”. The ASCII character code of 98 corresponds to the letter “b”.
A value of 25185 in register 1 will cause a string of “ba” to be written to a string tag if the /swapstring tag is NOT present on the interface command line and if location3=10203 (or location3=10204 depending on the type of register).
A value of 25185 in register 1 will cause a string of “ab” to be written to a string tag if the /swapstring tag is present on the interface command line and if location3=10203 (or location3=10204 depending on the type of register).
Order of Data Pre/Post Processing
When input data are read from a PLC, the raw data are processed in the following order:
1. Read Raw Data
2. Convert Binary or BCD, to Integer or Real
3. Apply the Bit Mask
4. Apply the Square Root Code
5. Apply the Conversion Factor, Span and Zero
6. Convert to PI Type R, I, or D for PI2 and to float16, float32, int16, int32, or digital for PI3.
7. When output data are written, the data are processed in the reverse order, but the bit mask conversion does not apply.
Performance Point Configuration
Performance points can be configured to monitor the amount of time in seconds that an interface takes to complete a scan for a particular scan class. The closer the scan completion time is to 0 seconds, the better the performance. The scan completion time is recorded to millisecond resolution.
Configuring Performance Points with PI ICU (Windows-Intel)
The PI Interface Configuration Utility (PI ICU) provides a user interface for creating and managing Performance Points.
[pic]
Create
To create a Performance Point, right mouse click the line belonging to the tag to be created, and select Create.
Delete
To delete a Performance Point, right mouse click the line belonging to the tag to be deleted, and select Delete.
Correct
If the “Status” of a point is marked “Incorrect”, the point configuration can be automatically corrected by ICU by right mouse clicking on the line belonging to the tag to be corrected, and selecting Correct. The Performance Points are created with the following PI attribute values. If ICU detects that a Performance Point is not defined with the following, it will be marked Incorrect:
|Attribute | Details |
|Tag |Tag name that appears in the list box |
|Point Source |Point Source for tags for this interface, as specified on the first tab |
|Compressing |Off |
|Excmax |0 |
|Descriptor |Interface name + “ Scan Class # Performance Point” |
Rename
To rename a Performance Point, right mouse click the line belonging to the tag to be renamed, and select “Rename”.
Status
The Status column in the Performance Points table indicates whether the Performance Point exists for the scan class in column 2.
• Created – Indicates that the Performance Point does exist
• Not Created – Indicates that the Performance Point does not exist
• Deleted – Indicates that a Performance Point existed, but was just deleted by the user
Scan Class
The Scan Class column indicates which scan class the Performance Point in the Tagname column belongs to. There will be one scan class in the Scan Class column for each scan class listed in the Scan Classes combo box on the General Parameters tab.
Tagname
The Tagname column holds the Performance Point tag name.
Snapshot
The Snapshot column holds the snapshot value of each Performance Point that exists in PI. The Snapshot column is updated when the Performance Points/Counters tab is clicked, and when the interface is first loaded.
Configuring Performance Points Manually
Performance point configuration is the same on all operating system platforms. Performance points are configured as follows.
1. Set the extended descriptor to:
PERFORMANCE_POINT
or to:
PERFORMANCE_POINT=interface_id
where interface_id corresponds to the identifier that is specified with the /id parameter on the startup command line of the interface. The character string PERFORMANCE_POINT is case insenstive. The interface_id does not need to be specified if there is only one copy of an interface that is associated with a particular point source.
2. Set Location4 to correspond to the scan class whose performance is to be monitored. For example, to monitor scan class 2, set Location4 to 2. See the /f parameter for a description of scan classes.
3. Set the PointSource attribute to correspond to the /ps parameter on the startup command line of the interface.
4. Set the PointType attribute to float32.
I/O Rate Tag Configuration
An I/O Rate point can be configured to receive 10-minute averages of the total number of exceptions per minute that are sent to PI by the interface. An exception is a value that has passed the exception specifications for a given PI point. Since 10-minute averages are taken, the first average is not written to PI until 10 minutes after the interface has started. One I/O Rate tag can be configured for each copy of the interface that is in use.
Monitoring I/O Rates on the Interface Node
For Windows nodes, the 10-minute rate averages (in events/minute) can be monitored with a client application such as ProcessBook.
Configuring I/O Rate Tags with PI ICU (NT-Intel)
The PI Interface Configuration Utility (PI ICU) provides a user interface for creating and managing IORates Tags.
[pic]
PI ICU currently allows for one I/O Rate tag to be configured for each copy of the interface that is in use. Some interfaces allow for multiple I/O Rates tags.
Enable IORates for this Interface
The Enable IORates for this interface check box enables or disables IORates for the current interface. To disable IORates for the selected interface, uncheck this box. To enable IORates for the selected interface, check this box.
Tag Status
The Tag Status column indicates whether the IORates tag exists in PI. The possible states are:
• Created – This status indicates that the tag exist in PI
• Not Created – This status indicates that the tag does not yet exist in PI
• Deleted – This status indicates that the tag has just been deleted
• Unknown – This status indicates that the ICU is not able to access the PI Server
In File
The In File column indicates whether the IORates tag listed in the tag name and the event counter is in the IORates.dat file. The possible states are:
• Yes – This status indicates that the tag name and event counter are in the IORates.dat file
• No – This status indicates that the tag name and event counter are not in the IORates.dat file
Event Counter
The Event Counter correlates a tag specified in the iorates.dat file with this copy of the interface. The command line equivalent is /ec=x, where x is the same number that is assigned to a tag name in the iorates.dat file.
Tagname
The tag name listed under the Tagname column is the name of the IORates tag.
Snapshot
The Snapshot column holds the snapshot value of the IORates tag, if the IORates tag exists in PI. The Snapshot column is updated when the IORates/Status Tags tab is clicked, and when the interface is first loaded.
Right Mouse Button Menu Options
Create
Create the suggested IORates tag with the tag name indicated in the Tagname column.
Delete
Delete the IORates tag listed in the Tagname column.
Rename
Allows the user to specify a new name for the IORates tag listed in the Tagname column.
Add to File
Adds the tag to the IORates.dat file with the event counter listed in the Event Counter Column.
Search
Allows the user to search the PI Server for a previously defined IORates tag.
Configuring I/O Rate Tags Manually
There are two configuration steps.
1. Configuring the PI Point on the PI Server
2. Configuration on the Interface Node
Configuring the PI Point on the PI Server
Create an I/O Rate Tag with the following point attribute values.
|Attribute |Value |
|PointSource |L |
|PointType |float32 |
|Compressing |0 |
|ExcDev |0 |
Configuration on the Interface Node
For the following examples, assume that the name of the PI tag is modbusE001, and that the name of the I/O Rate on the home node is modbusE001.
1. Edit/Create a file called iorates.dat in the PIHOME\dat directory. The PIHOME directory is defined either by the PIPCSHARE entry or the PIHOME entry in the pipc.ini file, which is located in the %windir% directory. If both are specified, the PIPCSHARE entry takes precedence.
Since the PIHOME directory is typically C:\PIPC, the full name of the iorates.dat file will typically be C:\PIPC\dat\iorates.dat.
Add a line in the iorates.dat file of the form:
modbusE001, x
where modbusE001 is the name of the I/O Rate Tag and x corresponds to the first instance of the /ec=x parameter in the startup command file. X can be any number between 2 and 34 or between 51 and 200, inclusive. To specify additional rate counters for additional copies of the interface, create additional I/O Rate tags and additional entries in the iorates.dat file. The event counter, /ec=x, should be unique for each copy of the interface.
2. Set the /ec=x parameter on the startup command file of the interface to match the event counter in the iorates.dat file.
The interface must be stopped and restarted in order for the I/O Rate tag to take effect. I/O Rates will not be written to the tag until 10 minutes after the interface is started.
Startup Command File
Command-line parameters can begin with a / or with a -. For example, the /ps=M and
–ps=M command-line parameters are equivalent. This interface uses the / by default.
For Windows, command file names have a .bat extension. The Windows continuation character (^) allows for the use of multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of parameters is unlimited, and the maximum length of each parameter is 1024 characters.
Configuring the Interface with PI ICU
The PI Interface Configuration Utility (PI ICU) provides a tool for configuring the Interface startup command file.
Note: PI ICU requires PI 3.3 or greater.
The PI Interface Configuration Utility provides a graphical user interface for configuring PI interfaces. If the interface is configured by the PI ICU, the batch file of the interface (modbusE.bat) will be maintained by the PI ICU and all configuration changes will be kept in that file. The procedure below describes the necessary steps for using PI ICU to configure the PI ModbusE Interface.
From the PI ICU menu, select Interface, NewWindowsInterface Instance from EXE …, and then Browse to the modbusE.exe executable file. Then, enter values for Point Source and Interface ID#. A window such as the following results:
[pic]
“Interface name as displayed in the ICU (optional)” will have PI- pre-pended to this name and it will be the display name in the services menu.
Click on Add.
You should then see a display such as the following:
[pic]
Note that in this example the Host PI System is localhost, which means that the interface will be configured to communicate with the local PI Server. However, if you want the interface to communicate with a remote PI Server, you can do this by selecting ‘Connections…’ item from PI ICU menu and make it your default server. If you do not see the remote node in the list of servers, you can add that in.
Once you add the interface to PI ICU, near the top of the main PI ICU screen, the Interface Type should be modbusE. If not, use the drop-down box to change the Interface Type to be modbusE.
Then add an entry for the Scan Classes. These are for scan based tags..
Click on Apply to enable the PI ICU to manage this copy of the PI ModbusE Interface.
[pic]
The next step is to make selections in the interface-specific tab (i.e. “modbusE”) that allow you to enter values for the startup parameters that are particular to the PI ModbusE Interface.
[pic]
Since the PI ModbusE Interface is a UniInt-based interface, in some cases the user will need to make appropriate selections in the UniInt tab. This tab allows the user to access UniInt features through the PI ICU and to make changes to the behavior of the interface.
To set up the interface as a Windows Service, use the Service tab. This tab allows you to configure the interface to run as a service as well as to start and stop the interface. You can also run the interface interactively from the PI ICU. To do that go to menu, select the Interface item and then Start Interactive.
For more detailed information on how to use the above-mentioned and other PI ICU tabs and selections, please refer to the PI Interface Configuration Utility User Manual. In the next section we will describe the selections that are available from the modbusE tab. After you have made your selections on the PI ICU GUI, you will need to press the Apply button in order for PI ICU to make these changes to the interface’s startup file.
modbusE Interface Tab
Since the startup file of the PI ModbusE Interface is maintained automatically by the PI ICU, you should use the modbusE tab to configure the startup parameters and not make changes in the file manually. The following is the description of interface configuration parameters used in the PI ICU Control and corresponding manual parameters.
General Parameters
[pic]
TCP/IP Port
This is the TCP/IP port number used to communicate with the PLC (default 502); (/PORT=portnumber).
Reconnect Interval Seconds
This is the reconnect interval in seconds when a connection fails for TCP/IP communications (default 30); (/RCI=x).
Communication Timeout Seconds
This defines the number of seconds the interface waits for an answer from the PLC before a timeout occurs (Range 1-10, default 2); (/TO=x).
# of Times to Send Request before I/O TIMEOUT
Defines a counter which equals the number of time that the interface will send a request for data before I/O TIMEOUT is written to the affected tags. (Range 1-4, default 1) (/CN=x);
Use Default
These buttons are used to set/reset the default values for each parameter. If they have been changed and you decide to go back to the default for a particular parameter clicking on the button will reset the default value back into the text box.
Swap Parameters
These 5 parameters are used to change the way bytes are interpreted from the PLC for each respective data type. See the command line parameter for more information.
• Data type 4 (/SWAP4)
• Data type 6 (/SWAP6)
• Data type 7 (/SWAP7)
• Data type 16 (/SWAP16)
• Data type 101+ (/SWAPSTRING)
Additional Parameters
In the space provided the user can supply additional parameters that are not available through the PI ICU control selections.
Advanced Parameters
This tab allows for more advanced parameters to be set. Also debugging information can be turned on.
[pic]
Don’t Use the Defacto Modbus TCP/IP Standard Designed by Modicon
Checking this box tells the ICU control not to use the Modbus TCP/IP standard which was designed by Modicon. When the /HCP is specified, the interface sends traditional Modbus packets (including a 2 byte CRC) without the 6-byte header as described in Modicon’s standards document; (/HCP)
Minimum Delay Time (milliseconds) between Scans
This is used to specify a minimum delay time between scans. (/POLLDELAY=x);
Wait Time (milliseconds) before Writing to Output Device
When this parameter is used the interface will wait x milliseconds before writing data to the output device; (/WRITEDELAY=x);
Request Length for Modbus Messages
The request length for Modbus message can be adjusted between 10 and 1000 bytes. The default is 100 bytes for function code 1 and 2 and 200 bytes for all other function codes. When the /REQUESTLEN parameter is used, the number of bytes that are read by all function codes are the same. This parameter should typically not need to be adjusted. (/REQUESTLEN=x)
Send bytes received from and sent to PLC to pipc.log
Checking this box will cause the interface to send the bytes sent to (if successful) and received from the PLC to the pipc.log file. (/MOD_DEBUG).
Command-line Parameters
The PI ModbusE interface requires several command-line parameters for successful execution. The parameters are set in a startup command file. This file is called modbusE#.bat, where # is the interface number. The command line must be on a single line and cannot exceed 1024 characters. Although the Windows continuation character (^) will work for creating a multi-line command when the interface is run interactively, the interface will not be able to parse the command line parameters when the interface is run as a service.
|Parameter |Description |
|/cn=# |Defines the counter number x, where x an integer from 1 to 4. The counter is |
|Optional |equal to the number of times that the interface will send a request for data |
|Default: /cn=1 |before IO Timeout is written to the affected tags. |
| |Temporary network glitches can cause the connection between the Modbus |
| |Ethernet interface and a PLC to be temporarily reset (WSAECONNRESET) or |
| |aborted (WSAECONNABORTED). If the interface fails to send a request for data |
| |as a result of either of these 2 errors and if the /cn paramter is set to a |
| |value greater than 1, the interface will immediately try to reconnect and |
| |gather data for the PLC. If the reason for the WSAECONNRESET or |
| |WSAECONNABORTED was cleared in the time period between scans, then the |
| |connection will be quickly reestablished and the interface will continue to |
| |collect data as if no network glitch had occurred. |
| |If /cn=1 (the default), all network glitches will cause an error to be written|
| |to the pipc.log file and the interface will not try to reconnect until the |
| |retry connection interval has elapsed as determined by the /rci parameter. |
| |If /cn=3 or /cn=4 and if the interface does not reconnect after the first |
| |retry, the interface could be suspended for a period of time equal to the |
| |timeout interval (as determined by the /to parameter) for every subsequent |
| |retry. This could potentially cause a delay in servicing other scan classes |
| |(see the /f parameter). |
|/ec=# |The first instance of the /ec parameter on the command line is used to specify|
|Optional |a counter number, x, for an I/O Rate point. If x is not specified, then the |
|Default: /ec=1 |default event counter is 1. Also, if the /ec parameter is not specified at |
| |all, there is still a default event counter of 1 associated with the |
| |interface. If there is an I/O Rate point that is associated with an event |
| |counter of 1, each copy of the interface that is running without /ec=x |
| |explicitly defined will write to the same I/O Rate point. This means that one |
| |should either explicitly define an event counter other than 1 for each copy of|
| |the interface or one should not associate any I/O Rate points with event |
| |counter 1. Configuration of I/O Rate points is discussed in the section called|
| |“I/O Rate Tag Configuration.” |
|/f=SS |The /f parameter defines the time period between scans in terms of hours (HH),|
|or |minutes (MM), and seconds (SS). The scans can be scheduled to occur at |
|/f=SS,SS |discrete moments in time with an optional time offset specified in terms of |
|or |hours (hh), minutes (mm), and seconds (ss). If HH and MM are omitted, then the|
|/f=HH:MM:SS |time period that is specified is assumed to be in seconds. |
|or |Each instance of the /f parameter on the command line defines a scan class for|
|/f=HH:MM:SS,hh:mm:ss |the interface. There is no limit to the number of scan classes that can be |
|Required for scan-based points |defined. The first occurrence of the /f parameter on the command line defines |
|Default: none |the first scan class of the interface, the second occurrence defines the |
| |second scan class, and so on. PI Points are associated with a particular scan |
| |class via the Location4 PI Point attribute. For example, all PI Points that |
| |have Location4 set to 1 will receive input values at the frequency defined by |
| |the first scan class. Similarly, all points that have Location4 set to 2 will |
| |receive input values at the frequency specified by the second scan class, and |
| |so on. |
| |Two scan classes are defined in the following example: |
| |/f=00:01:00,00:00:05 /f=00:00:07 |
| |or, equivalently: |
| |/f=60,5 /f=7 |
| |The first scan class has a scanning frequency of 1 minute with an offset of |
| |5 seconds, and the second scan class has a scanning frequency of 7 seconds |
| |with no offset. |
| |When no offset is specified, the scan class will be scheduled for immediate |
| |execution. That is, the interface will not wait for a well-defined moment in |
| |time before scanning when no offset is specified. |
| |When an offset is specified, the scans occur at well-defined moments in time |
| |according to the formula: |
| |scan times = (reference time) + n(frequency) + offset |
| |where n is an integer and the “reference time” is midnight on the day that the|
| |interface was started. In the above example, “frequency” is 60 seconds and |
| |“offset” is 5 seconds for the first scan class. This means that if the |
| |interface was started at 05:06:06, the first scan would be at 05:07:05, the |
| |second scan would be at 05:08:05, and so on. |
| |There is no guarantee that a scan will occur at the interval defined by the |
| |scan class. If the interface is under a large load, then some scans may occur|
| |late or be skipped entirely. See the section called “Performance Point |
| |Configuration” for more information on skipped or missed scans. |
| |Sub-second Scan Classes |
| |One can also specify sub-second scan classes on the command line such as |
| |/f=0.5 /f=00:00:00.1 |
| |where the scanning frequency associated with the first scan class is 0.5 |
| |seconds and the scanning frequency associated with the second scan class is |
| |0.1 seconds. |
| |Similarly, sub-second scan classes with sub-second offsets can be defined, |
| |such as |
| |/f=0.5,0.2 /f=1,0 |
| | |
| |Wall Clock Scheduling |
| |Scan classes that strictly adhere to wall clock scheduling are now possible. |
| |This feature is available for interfaces that run on NT and/or UNIX. |
| |Previously, wall clock scheduling was possible, but not across daylight |
| |savings time. For example, /f=24:00:00,08:00:00 corresponds to 1 scan a day |
| |starting at 8 AM. However, after a Daylight Savings Time change, the scan |
| |would occur either at 7 AM or 9 AM, depending upon the direction of the time |
| |shift. To schedule a scan once a day at 8 AM (even across daylight savings |
| |time), one should use /f=24:00:00,00:08:00,L. The ,L at the end of the scan |
| |class tells UniInt to use the new wall clock scheduling algorithm. |
|/hcp |When this parameter is on the command line, the defacto Modbus TCPIP standard |
|Optional, |designed by Modicon is not used. The defacto standard is described at: |
|No default. | |
| |When the /hcp is specified, the interface sends traditional Modbus packets |
| |(including a 2-byte CRC) without the 6-byte header as described in Modicon's |
| |standards document. |
|/host=host:port |The /host parameter is used to specify the PI Home node. Host is the IP |
|Required |address of the PI Sever node or the domain name of the PI Server node. Port |
|Default: see right |is the port number for TCP/IP communication. The port is always 5450 for a |
| |PI 3 Server and 545 for a PI 2 Server. It is recommended to explicitly define |
| |the host and port on the command line with the /host parameter. Nevertheless, |
| |if either the host or port is not specified, the interface will attempt to use|
| |defaults. |
| |Defaults: |
| |The default port name and server name is specified in the pilogin.ini or |
| |piclient.ini file. The piclient.ini file is ignored if a pilogin.ini file is |
| |found. Refer to the PI-API manual for more information on the piclient.ini and|
| |pilogin.ini files. |
| |Examples: |
| |The interface is running on a PI Interface Node, the domain name of the |
| |PI 3 home node is Marvin, and the IP address of Marvin is 206.79.198.30. Valid|
| |/host parameters would be: |
| |/host=marvin |
| |/host=marvin:5450 |
| |/host=206.79.198.30 |
| |/host=206.79.198.30:5450 |
|/id=# |The /id parameter is used to specify the interface identifier. |
|Required |The interface identifier is a string that is no longer than 9 characters in |
|Default: none |length. UniInt concatenates this string to the header that is used to identify|
| |error messages as belonging to a particular interface. See the section called |
| |“Error and Informational Messages” for more information. |
| |UniInt always uses the /id parameter in the fashion described above. This |
| |interface also uses the /id parameter to identify a particular interface copy |
| |number that corresponds to an integer value that is assigned to Location1. For|
| |this interface, one should use only numeric characters in the identifier. For |
| |example, |
| |/id=1 |
|/mod_debug |When this parameter is sent, the bytes that are sent to and received from the |
|Optional |PLC are written to the pipc.log file. |
|/net=x |This command line parameter is no longer required because the only supported |
|Obsolete |option is /net=TCP. |
|Default: /net=TCP |The unsupported modes are /net=none and /net=plus. |
|/polldelay=x |The /polldelay parameter is used to specify a minimum delay time between |
|Optional |scans. x is the delay time in milliseconds. |
|Default: |Sometimes it is possible for the Modbus interface to send commands to the DCS |
|/polldelay=0 |at a faster rate than the DCS can handle. This is most likely to happen when|
| |there are 2 overlapping scan classes reading from the same node. |
|/port=# |The TCP/IP port through which the interface connects to a particular IP |
|Optional |address. The default port is the “well-known port of 502.” |
|Default: /port=502 | |
|/ps=x |The /ps parameter specifies the point source for the interface. X is not case |
|Required |sensitive and can be any single character. For example, /ps=M and /ps=m are |
|Default: none |equivalent. |
| |The point source that is assigned with the /ps parameter corresponds to the |
| |PointSource attribute of individual PI Points. The interface will attempt to |
| |load only those PI points with the appropriate point source. |
|/q |When the /q parameter is present, Snapshots and exceptions are queued before |
|Optional |they are sent to the PI Server node. |
|Default: no queuing |The maximum queue size is 255 bytes for a PI 3 Server and 36 bytes for a PI 2 |
| |Server. For example, if the interface is running on a UNIX node and is |
| |communicating to a PI 2 Server, then the maximum queue size is 36. The queue |
| |is flushed between scans if it is not filled. |
| |When the /q parameter is specified in non-extended API mode, the PI-API sends |
| |integer values as 16-bit integers instead of 32-bit integers. Therefore, |
| |integer points will be limited to values between 0 and 32767. Values higher |
| |than 32767 need to be sent to floating-point PI tags. |
|/rci=# |The /rci parameter is used to specify the reconnect interval in seconds when a|
|Optional |connection fails for TCP/IP communication. Unless the /cn parameter is set to|
|Default : /rci=30 |a value greater than 1, the interface will not try to reconnect until the |
| |reconnection interval has expired. |
|/requestlen=# |The request length for Modbus messages can be adjusted between 10 and 1000 |
|Optional, |bytes. The default is 100 bytes for function codes 1 and 2 and 200 bytes for |
|See description for default |the remaining function codes. When the /requestlen parameter is used, the |
| |number of bytes that are read by all function codes are the same. This |
| |parameter should typically not need to be adjusted. |
|/sio |The /sio parameter stands for “suppress initial outputs.” The parameter |
|Optional |applies only for interfaces that support outputs. If the /sio parameter is not|
| |specified, the interface will behave in the following manner. |
| |When the interface is started, the interface determines the current Snapshot |
| |value of each output tag. Next, the interface writes this value to each output|
| |tag. In addition, whenever an individual output tag is edited while the |
| |interface is running, the interface will write the current Snapshot value to |
| |the edited output tag. |
| |This behavior is suppressed if the /sio parameter is specified on the command |
| |line. That is, outputs will not be written when the interface starts or when |
| |an output tag is edited. In other words, when the /sio parameter is specified,|
| |outputs will only be written when they are explicitly triggered. |
|/stopstat |If the /stopstat parameter is present on the startup command line, then the |
|or |digital state Intf shut will be written to each PI Point when the interface is|
|/stopatat= |stopped. |
|digstate |If /stopstat=digstate is present on the command line, then the digital state, |
|Optional |digstate, will be written to each PI Point when the interface is stopped. For |
|Default: |a PI 3 Server, digstate must be in the system digital state table. For a |
|/stopstat= |PI 2 Server, where there is only one digital state table available, digstate |
|”Intf shut” |must simply be somewhere in the table. UniInt uses the first occurrence in the|
| |table. |
| |If neither /stopstat nor /stopstat=digstate is specified on the command line, |
| |then no digital states will be written when the interface is shut down. |
| |Examples: |
| |/stopstat=”Intf shut” |
| |The entire parameter is enclosed within double quotes when there is a space in|
| |digstate. |
|/swap4 |This parameter is used only in conjunction with floating points of data type |
|Optional |4. When the /swap4 parameter is specified, the interface will expect the |
| |bytes that are sent from the PLC in a different order than the default order. |
|/swap6 |This parameter is used only in conjunction with floating points of data type |
|Optional |6. This parameter is required with Modicon PLCs if floating points of data |
| |type 6 are being using. When the /swap6 parameter is specified, the interface|
| |will expect the bytes that are sent from the PLC in a different order than the|
| |default order. |
|/swap7 |This parameter is used only in conjunction with points of data type 7 (see |
|Optional |location3 under “PI Point Definition”). Some PLCs store 4-byte integers with |
| |the high and low bytes swapped from the default order that the PI ModbusE |
| |interface is expecting (see Appendix D). If this is the case, the /swap7 |
| |parameter will need to be specified as a command-line parameter. |
|/swap16 |This parameter is used only in conjunction with data type 16 (double precision|
|Optional |IEEE floating point). When the /swap16 parameter is specified, the interface|
| |will expect the bytes that are sent from the PLC in a different order than the|
| |default order. |
|/swapstring |This parameter is used in conjunction with data types 101 and higher. These |
|Optional |data types are for reading strings of varying lengths into PI tags (see |
| |location3 under “PI Point Definition”). The /SwapString parameter reverses |
| |the byte order in each 16-byte register. |
|/to=# |Defines the number of seconds, x, that the interface waits for an answer from |
|Optional |the PLC before a timeout occurs. X is an integer from 1 to 300. The default |
|Default: /to=2 |is 2 seconds. |
|/writedelay=# |If this parameter is used, the interface will wait x milliseconds before |
|Optional |writing data to the output device. This is the minimum time between outputs |
|Default: |to a PLC. |
|/writedelay=0 | |
Sample ModbusE.bat File
REM ModbusE.bat
REM --------------------------------------------------------------
REM Sample startup file for the Modbus Ethernet on Windows
REM Interface to the PI System
REM --------------------------------------------------------------
REM OSIsoft recommends using PI ICU to modify startup files
REM --------------------------------------------------------------
REM
REM EDIT THE NEXT LINE AS APPROPRIATE. Add command-line
REM parameters as REM needed.
.\modbuse.exe /id=1 /ps=m /q /f=5 /host=localhost:5450
REM
REM End ModbusE.bat
REM --------------------------------------------------------------
Interface Node Clock
Make sure that the time and time zone settings on the computer are correct. To confirm, run the Date/Time applet located in the Windows Control Panel. If the locale where the interface node resides observes Daylight Saving Time, check the box marked “Automatically adjust clock for daylight saving changes”. For example,
[pic]
In addition, make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. That is,
C:> set
Make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. Confirm that TZ is not in the resulting list. If it is, run the System applet of the Control Panel, click the Environment tab, and remove TZ from the list of environment variables.
Security
Windows
The PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Server. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Server manuals.
Note that the Trust Database, which is maintained by the Base Subsystem, replaces the Proxy Database used prior to PI version 3.3. The Trust Database maintains all the functionality of the proxy mechanism while being more secure.
See “Trust Login Security” in the chapter “PI System Management” of the PI Universal Data Server System Management Guide.
If the interface cannot write data to the PI Server because it has insufficient privileges, a –10401 error will be reported in the pipc.log file. If the interface cannot send data to a PI2 Serve, it writes a –999 error. See the section “Appendix A: Error and Informational Messages” for additional information on error messaging.
PI Server v3.3 and Higher
Security configuration using piconfig
For PI Server v3.3 and higher, the following example demonstrates how to edit the PI Trust table:
C:\PI\adm> piconfig
@table pitrust
@mode create
@istr Trust,IPAddr,NetMask,PIUser
a_trust_name,192.168.100.11,255.255.255.255,piadmin
@quit
For the above,
Trust: An arbitrary name for the trust table entry; in the above example,
a_trust_name
IPAddr: the IP Address of the computer running the Interface; in the above example,
192.168.100.11
NetMask: the network mask; 255.255.255.255 specifies an exact match with IPAddr
PIUser: the PI user the Interface to be entrusted as; piadmin is usually an appropriate user
Security Configuring using Trust Editor
The Trust Editor plug-in for PI System Management Tools 3.x may also be used to edit the PI Trust table.
See the PI System Management chapter in the PI Server manual for more details on security configuration.
PI Server v3.2
For PI Server v3.2, the following example demonstrates how to edit the PI Proxy table:
C:\PI\adm> piconfig
@table pi_gen,piproxy
@mode create
@istr host,proxyaccount
piapimachine,piadmin
@quit
In place of piapimachine, put the name of the PI Interface node as it is seen by PI Server.
Starting / Stopping the Interface
This section describes starting and stopping the interface once it has been installed as a service. See the UniInt End User Document to run the interface interactively.
[pic]
Starting Interface as a Service
If the interface was installed as a service, it can be started from PI ICU, the services control panel or with the command:
modbusE.exe –start
To start the interface service with PI ICU, use the [pic] button on the PI ICU toolbar.
A message will inform the user of the the status of the interface service. Even if the message indicates that the service has started successfully, double check through the Services control panel applet. Services may terminate immediately after startup for a variety of reasons, and one typical reason is that the service is not able to find the command-line parameters in the associated .bat file. Verify that the root name of the .bat file and the .exe file are the same, and that the .bat file and the .exe file are in the same directory. Further troubleshooting of services might require consulting the pipc.log file, Windows Event Viewer, or other sources of log messages. See the section “Appendix A: Error and Informational Messages,” for additional information.
Stopping Interface Running as a Service
If the interface was installed a service, it can be stopped at any time from PI ICU, the services control panel or with the command:
modbusE.exe –stop
The service can be removed by:
modbusE.exe –remove
To stop the interface service with PI ICU, use the [pic] button on the PI ICU toolbar.
Buffering
For complete information on buffering, please refer to the PI-API Installation Instruction.
PI Interface Node buffering consists of a buffering process which runs continuously on the local node, a PI-API library whose calls can send data to this buffering process, and a utility program for examining the state of buffering and controlling the buffering process.
Note: Change the Local Security Policy on Windows XP.
1. Open "Administrative Tools" from the control panel.
2. Open "Local Security Policy" from administrative tools.
3. Browse to "Security Options" under "Local Policies."
4. Double click on "System Objects: Default owner for objects created by members of the Administrators group."
5. Change the dropdown from "Object Creator" to "Administrators group."
The behavior of Bufserv should now be the same on XP as it was for NT4 and 2000.
Configuring Buffering with PI ICU (Windows-Intel)
Buffering is enabled through the PI Interface Configuration Utility’s Tools>API Buffering… menu. Unless buffering is explicitly enabled, the PI-API will not buffer data, sending data directly to the home node.
The API Buffering… dialog allows the user to view and configure the parameters associated with the API Buffering (bufserv) process. The user can create or remove API Buffering as a service from the Service tab. In addition, the user can start and stop the API Buffering process from the Service tab:
[pic]
Service Tab
The Service tab allows for some API Buffering service configuration. For further configuration changes, use the Services applet.
Service Name
The Service name displays the name of the API Buffering Service.
Display Name
The Display name displays the full name associated with the API Buffering service.
Log On As
Log on as indicates the Windows user account under which the PI API Buffering service is setup to start automatically on reboot, or manually.
Password
Password is the name of the password for the Windows user account entered in the Log on as:above.
Confirm password
Reenter the password to verify it has been typed correctly both times.
Dependencies
The Dependencies lists the Windows services on which the API Buffering service is dependent.
Dependent Services
The Dependent Services lists the Windows services which depend on the API Buffering service (bufserv).
Service Startup Type
The Startup Type indicates whether the API Buffering service is setup to start automatically on reboot or manually on reboot, or is disabled.
• If the Auto option is selected, the service will be installed to start automatically when the machine reboots.
• If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.
• If the Disabled option is selected, the service will not start at all.
Generally, the API Buffering service is set to start automatically.
Start / Stop Service
The Start / Stop buttons allow for the API Buffering service to be started and stopped. After a change is made to any of the settings on the Settings tab, the Save button must be clicked, and then the service must be stopped and restarted for the changes to be picked up by Bufserv.
Create / Remove Service
The Create / Remove buttons allow for the API Buffering service to be created or removed from the Window Services. Bufserv also can be create and removed manually.
Settings Tab
The Settings tab allows for configuration of the 7 configurable settings used by API Buffering. Default values are used if no other value is provided.
[pic]
Enable API Buffering
Enables the API Buffering feature.
Maximum File Size
Maximum buffer file size in kilobytes before buffering fails and discards events. Default value is 100,000. Range is 1 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Send Rate
Send rate is the time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds). Default value is 100. Range is 0 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Primary Memory Buffer Size
Primary memory buffer size is the size in bytes of the Primary memory buffer. Default value is 32768. Range is 64 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Secondary Memory Buffer Size
Secondary memory buffer size is the size in bytes of the Secondary memory buffer. Default value is 32768. Range is 64 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Max Transfer Objects
Max transfer objects is the maximum number of events to send between each SENDRATE pause. Default value is 500. Range is 1 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Pause Rate
When buffers are empty the buffering process will wait for this number of seconds before attempting to send more data to the home node. Default value is 2. Range is 0 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Retry Rate
When the buffering process discovers the home node is unavailable it will wait this number of seconds before attempting to reconnect. Default value is 120. Range is 0 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Max Theoretical Send Rate
This is the theoretical max send rate is calculated like this:
max = MAXTRANSFEROBJS / SENDRATE * 1000
Default value is 5000.
There are no additional steps needed to install buffering after installing the PI-API. The delivered PI-API library supports both buffered and un-buffered calls.
Configuring Buffering Manually
Buffering is enabled through the use of a configuration file, piclient.ini. Unless this file is modified to explicitly enable buffering, the PI-API will not buffer data, sending data directly to the home node.
There are no additional steps needed to install buffering after installing the PI-API. The delivered PI-API library supports both buffered and un-buffered calls.
Note: When buffering is configured to be on, the bufserv process must be started before other programs using the PI-API, so that these programs can access the shared buffering resources. Any program that makes a connection to a PI Server has this requirement even if it does not write to PI.
Configuration of buffering is achieved through entries in the piclient.ini file. The file is found in the .dat subdirectory of the PIHOME directory (typically c:\pipc\dat) under Windows NT. This file follows the conventions of Microsoft Windows initialization files with sections, keywords within sections, and values for keywords. All buffering settings are entered in a section called [APIBUFFER]. To modify settings, simply edit the piclient.ini file in a text editor (Notepad on Windows) to the desired values.
The following settings are available for buffering configuration:
|Keywords |Values |Default |Description |
|BUFFERING |0,1 |0 |Turn off/on buffering. OFF = 0, ON = 1, |
|PAUSERATE |0 – 2,000,000 |2 |When buffers are empty the buffering process will |
| | | |wait for this long before attempting to send more |
| | | |data to the home node (seconds) |
|RETRYRATE |0 – 2,000,000 |120 |When the buffering process discovers the home node |
| | | |is unavailable it will wait this long before |
| | | |attempting to reconnect (seconds) |
|MAXFILESIZE |1 – 2,000,000 |100,000 |Maximum buffer file size before buffering fails and|
| | | |discards events. (Kbytes) |
|MAXTRANSFEROBJS |1 – 2,000,000 |500 |Maximum number of events to send between each |
| | | |SENDRATE pause. |
|BUF1SIZE |64 – 2,000,000 |32768 |Primary memory buffer size. (bytes) |
|BUF2SIZE |64 – 2,000,000 |32768 |Secondary memory buffer size. (bytes) |
|SENDRATE |0 – 2,000,000 |100 |The time to wait between sending up to |
| | | |MAXTRANSFEROBJS to the server (milliseconds) |
In addition to the [APIBUFFER] section, the [PISERVER] section may be used to define the default PI server and an optional time offset change that may occur between the client and server.
|Keywords |Values |Default |Description |
|PIHOMENODE |string |none |Windows default server is in pilogin.ini |
|DSTMISMATCH |0 – 2,000,000 |0 |The time that the server and client local time offset |
| | | |is allowed to jump. Typically, 3600 if the nodes are |
| | | |in time zones whose DST rules differ (seconds) |
Example piclient.ini File
On Windows the default server information is stored in the pilogin.ini file so the piclient.ini would only have the [APIBUFFER] section. The BUFFERING=1 indicates that buffering is on. The MAXFILESIZE entry in Kbytes of 100000 allows up to 100 Megabytes of data storage. Do not use commas or other separators in the numeric entries. The retry rate is set to 600 seconds meaning wait 10 minutes after losing a connection before retrying.
On Windows a piclient.ini file might look like:
[APIBUFFER]
BUFFERING=1
MAXFILESIZE=100000
; The PI-API connection routines have a 1 minute default timeout.
RETRYRATE=600
Appendix A:
Error and Informational Messages
A string NameID is pre-pended to error messages written to the message log. Name is a non-configurable identifier that is no longer than 9 characters. ID is a configurable identifier that is no longer than 9 characters and is specified using the /id parameter on the startup command line.
Message Logs
The location of the message log depends upon the platform on which the interface is running. See the UniInt End User Document for more information.
Messages are written to PIHOME\dat\pipc.log at the following times.
• When the interface starts many informational messages are written to the log. These include the version of the interface, the version of UniInt, the command-line parameters used, and the number of points.
• As the interface retrieves points, messages are sent to the log if there are any problems with the configuration of the points.
• If the /db is used on the command line, then various informational messages are written to the log file.
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:
Windows: \PI\adm\pidiag –e error_number
Appendix B:
Data Access Table
For security purposes, the user may wish to restrict the range of registers, coils, etc., that the Modbus Interface can read from or write to. The accessible ranges can be configured in an optional data access table. The accessible registers, coils, etc., can be configured differently for different PLC nodes. If no Data Access Table is found by the interface, default minimum and maximum values will be assigned.
One Data Access Table can be configured for each version of the interface that is running. This file must be called ModbusE#.dat, where # should be replaced by the interface number as specified by the /id parameter on the startup command line of the interface. The ModbusE#.dat file should be placed in the PIHOME\dat directory. The PIHOME directory is determined by the PIHOME or the PIPCSHARE entry in the pipc.ini file (located in the WinNT directory). The PIPCSHARE entry takes precedence when both PIHOME and PIPCSHARE are defined. For example, if the PIHOME entry is c:\PIPC, then the ModbusE#.dat file should be placed in the c:\PIPC\dat directory.
If the data access table is added, deleted or modified, the interface must be restarted before the new values will take effect.
If the user configures a PI tag (say mb:read.1) with a coil or register address that is out of range, the ModbusE interface will respond with the following error message:
ModbusE #> Load PI point Failed, Cannot access
a valid register (or address), for Tag: mb:read.1
An example of a data access table file is given below. Note that comments lines are denoted by an * character in the first column. A template of this file called ModbusE.dat.template is provided in the PIHOME\Interfaces\ModbusE directory. This file should be edited to accommodate the user’s needs and then placed in the PIHOME\dat directory with the name ModbusE#.dat.
** Template file for data access table
* 26-Aug-97 GWM, OSIsoft, Inc.
*
* "*" points serve as comment markers.
*
* This file is used to assign the minimum and maximum
* coil/register addresses.
*
* If no Data Access Table is provided, the following default
* ranges are used for the given items:
*
* ITEM: DEFAULT VALUE:
* -------------------------- ------------
* The Minimum Register/Coil Value 1
* The Maximum Register/Coil Value 65,536
*
* SYNTAX
*
* The syntax is:
* 'Node','Function code','Minimum','Maximum'
*
* ------------------
* EXAMPLE FOR MODBUS
* For Modicon hardware, function codes 1 and 5 begin at coil 1,
* function code 2 begins at input 10001, function code 3 and 6
* begin at holding register 40001, and function code 4 begins
* at holding register 30001. To restrict access to certain
* coils, registers, etc., offset values from 0, 10000, 40000,
* and 30000 need to be provided. To restrict data access to
* the first 96 coil, registers, etc., for each function code
* and for PLC node 1, the following syntax is used:
*
* Uncomment the next six lines to implement this example
* 1,1,1,96
* 1,2,1,96
* 1,3,1,96
* 1,4,1,96
* 1,5,1,96
* 1,6,1,96
*
** end of Data Access File
Appendix C:
Modbus Message Packets
The message packets that are described below correspond to the Modbus protocol. These packets are embedded within TCP/IP framing.
Function Codes 1 - 4
Message Packet Sent to PLC
Byte 0: PLC node address
Byte 1: Function code.
Byte 2: High-order byte specifying the first coil or register address.
Byte 3: Low-order byte specifying the first coil or register address.
Byte 4: High-order byte specifying the number of coils or registers to be accessed.
Byte 5: Low-order byte specifying the number of coils or registers to be accessed.
Message Packet Returned by PLC
Byte 0: PLC node address.
Byte 1: Function code.
Byte 2: Number of bytes of data returned.
Byte 3: Data
Byte 4: Data
…
Byte N: Data
Function Codes 5 - 6
Message Packet Sent to PLC (Except for Data Type 4)
Byte 0: PLC node address.
Byte 1: Function code.
Byte 2: High-order byte of coil or register address.
Byte 3: Low-order byte of coil or register address.
Byte 4: High-order data byte sent to coil or register.
Byte 5: Low-order data byte sent to coil or register.
Message Packet Sent to PLC (Data Type 4)
Byte 0: PLC node address.
Byte 1: Function code.
Byte 2: High-order byte of coil or register address.
Byte 3: Low-order byte of coil or register address.
Byte 4: High-order data byte sent to coil or register.
Byte 5: Low-order data byte sent to coil or register.
Byte 6: High-order data byte sent to coil or register.
Byte 7: Low-order data byte sent to coil or register.
Message Packet Returned by PLC
The PLC returns the same bytes that were received.
Function Code 16
Message Packet Sent to PLC
Byte 0: PLC node address.
Byte 1: Function code.
Byte 2: High-order byte specifying the first register address to be written to.
Byte 3: Low-order byte specifying the first register address to be written to.
Byte 4: High-order byte specifying the number of registers to be accessed, which is always set to 0 for OSIsoft’s Modbus interface to the PI system.
Byte 5: Low-order byte specifying the number of registers to be accessed, which is always set to 2 for OSIsoft’s Modbus interface to the PI system.
Byte 6: Number of bytes of data to be sent to PLC.
Byte 7: High-order data byte sent to first register.
Byte 8: Low-order data byte sent to first register.
Byte 9: High-order data byte sent to second register.
Byte 10: High-order data byte sent to second register.
Message Packet Returned by PLC
The PLC returns the first 6 bytes that were received (bytes 0 to 5).
Appendix D:
Floating Point Representation
The manner in which PLCs store floating-point numbers vary. As a result, the Modbus commands that are needed to retrieve floating point values will also vary from PLC to PLC. The user can specify the manner in which the PLC stores a floating point with the data type parameter that is discussed under “Point Definition” earlier in this manual.
_______________________________________________________________________
NOTE: To make matters more complicated for the software developer, different operating systems (e.g. NT, VAX, UNIX) store IEEE floating point numbers differently. Standard 4-byte IEEE floating points on Intel NT are represented as follows:
byte 3: S MSBE E E E E E E
byte 2: LSBE MSBF F F F F F F
byte 1: F F F F F F F F
byte 0: F F F F F F F LSBF
where,
S = sign bit (1 = -)
MSBE = most significant bit exponent
LSBE = least significant bit exponent
MSBF = most significant bit fraction
LSBF = least significant bit fraction
For example, the number 1 is stored as a floating-point number by:
byte 0 = 0 byte 1 = 0 byte 2 = 0x80 byte 3 = 0x3f
where 0x80 and 0x3f are hexadecimal numbers.
_______________________________________________________________________
All floating-point values will be returned in two registers. For purposes of discussion, the “low-order register” will contain bytes 0 and 1, and the “high-order register” will contain bytes 2 and 3. This definition is somewhat arbitrary because the byte order is reversed, for example, on VAX platforms. Hence the “low” and “high” order bytes are swapped. Also, there is no good reason to consider byte 3 (the byte with the exponent) of higher order than byte 1 or byte 0 (bytes containing the fraction).
Some PLC’s will send the low register back first and then the high register, while other PLC’s will send the high register back first and then the low register. The order in which the Modbus interface expect the bytes is different for each data type (see below).
The interface currently supports 3 different methods of reading and writing IEEE floating point numbers. Data types 4, 5 and 6 (defined in the Location3) are IEEE floating points. The interface can also read Siemens type floating point values (data type 8), but writes of Seamen floats are not supported. 4-byte integers (data type 7) are also discussed below.
Data Type 4, Floating Point
This type of PLC maps a single register to 2 different registers that contain the floating-point value. For example register 235 could point to the floating-point value contained in registers 625 and 626, and register 236 could point to the floating-point value contained in registers 888 and 889. For the request sent to the PLC, the number of data registers specified will be 1 per floating point. By default the Modbus Interface expects the low order register first followed by the high order register. The Fisher Remote Operational Controller (ROC) Emulation uses this type of floating point.
Data Type 5, Floating Point
This type of PLC stores a floating point in two consecutive registers; for example registers 625 and 626. The interesting thing about this floating point type is that for each request sent to the PLC, the number of data registers specified is 1 per floating point. By default, the Modbus interface expects the low order register first followed by the high order register. The SOLAR APRIL-5000 PLC uses this type of floating point.
Data Type 6, Floating Point
This type of PLC also stores a floating point in two consecutive registers. However the request to the PLC must specify 2 data registers per floating point. The default is to expect the high order register first followed by the low order register. The GE 9070 and Micro Motion Mass Flow Meters return the bytes in this order. Modicon PLCs return the low order register first followed by the high-order register. Hence, the /swap6 parameter should be specified in the startup command file for Modicon PLCs.
Data Type 7, Binary Data, 4-byte Integer, Floating Points as
4-byte Integers
Certain devices, such as the Motherwell Controls Series 5000 Tank Gauging System, represent floating point numbers in an integer format. These values require division by a conversion factor to convert them from integers to their proper floating point value. For example, the floating-point value of 16.4 can be represented by a 2 byte integer containing the value of 164: byte0 = 0, byte1 = 164 (decimal). A conversion factor of 10 is used (the raw value is divided by 10) to convert the value to 16.4. A floating-point value of -16.4 can be represented by a 2 byte integer containing -164; byte0 = 255, byte1 = 92. Again the value is divided by the conversion factor, 10, to yield -16.4. The integer range for 2 byte integers is (-32768) to (32767).
Four (4) byte integers can also be used to hold floating point numbers. The same conversion equation that applies to 2 byte integers applies to 4 byte integers as well. Data type 7 is used to indicate that data will be 4 byte integer values. The integer range for 4 byte integers is (-2147483648) to (2147483647).
The Square Root Code should be set to 3 to indicate the integer to floating point conversion as described above. The appropriate Conversion Factor should be entered and the Point Type should be R. For integer representation, only the following Location3 entries are supported at the present time: 103, 104, 703, 704 and (for write) 106, 706.
The default is for the Modbus interface to expect the high order register first.
Data Type 8, Siemens Floating Point
Siemens Floating points are supported only for inputs.
The Siemens PLC uses a special bitmap representation. The float bitmap representation is listed below:
Bits map: 31 30 29 28 27 26 25 24 23 22 21 20 ....................................01 00
Siemens: S X X X X X X X S M M M ...................................M M
where: S=Sign Bits, X=Exponent Bits, and M=Mantissa
Bit31 is the sign bit of the exponent,
Bit30 to Bit24 represent a decimal value of [pic].....[pic] (64 ... 1) and are used to compose the exponent,
Bit23 is the sign bit of the mantissa,
bit22 to Bit00 represent a decimal value of [pic].....[pic] and are used to compose the mantissa.
The following formula is used to generate the decimal value from the four bytes that are sent:
[pic]
Where Mantissa is formed as follows:
[pic]
and the Exponent:
[pic]
The default is for the Modbus interface to expect the high order register first
Data Type 9
Data type 9 is analogous to data type 4, except that the Modbus interface expects an IEEE floating point value to be stored in the 4-byte register when data type 4 is specified and the Modbus interface expects a 4-byte integer to be stored in the 4-byte register when data type 9 is specified.
Function Code 65
Some PLC’s are able to understand function code 65, which is a non-standard modbus function code. One type of PLC that understands function code 65 is called an HTMUX box. If such a PLC receives function code 65, it knows that a 4-byte floating point should be returned.
Each register that can be read with function code 65 contains 4 bytes of information. Standard registers can hold only two bytes of information. Function code 65 is similar to data type 4 above, except that there is no need to map a single register to two different registers. Each register can already hold 4 bytes.
Appendix E:
PLC Notes
The following are PLCs that have been known to work against the Modbus interface. This list is by no means complete, and it is not being actively updated. There are just too many devices out there that supports Modbus to keep track of them all. If your PLC supports Modbus communication, our interface should work with it. Just because a PLC is not listed below, does not mean that we do not support that PLC. A good way to test whether your PLC will work with our interface is to test it with ModScan, which is available at WinTECH Software’s website: .
• Modicon 984 Series PLCs
• Modicon Quantum PLCs
• Honeywell 620 Series PLCs
• GE 9070 PLCs
• GE Speedtronic Mark V control system
• Rosemont Hydrostatic Interface Unit (HIU) Tank Gauging System
• SOLAR APRIL-5000 PLCs
• Fisher Remote Operational Controller (ROC) Emulation
• Chessel PLC
• Field Electronic Limited PLC 2000
• Micro Motion ELITE Model RFT9739 Transmitter (Mass Flow Meter)
• ESC8816 Environmental Monitor
• Motherwell Controls Series 5000 Tank Gauging System
• Siemens S5 PLC
• Omni Flow Computers, Series 6000
• Fisher-Rosemount ValveLink VL2030 Software
• SquareD PLC through Network Interface Module CRM-570
The SquareD PLC requires non-standard setup. A customer who set up communication to a SquareD PLC sent the following e-mail message after solving the communication problems that he was having: “The problem lies with the setting of the NIM. Port 0 (connected to PI-API node) should set to SY/MAX mode, whereby port 1 (connected to PLC processor) should set to Application mode #2.”
• Opto22
Appendix F:
Simulators
Frequently, problems with incorrect values being read by the Modbus Interface can be resolved if the user can read the PLC registers independently of the Modbus interface. For example, the user may not know how his or her particular PLC stores floating-point numbers. Many PLC’s store floating point numbers in two consecutive registers, but this is not always the case. It is important to know how the PLC stores floating point numbers because one needs to specify a data type for the PI Point. For a given data type, the Modbus interface assumes that the PLC stores data in a particular way. If the user can display the register data with an independent program, then the user can determine whether or not the values correspond to the expected floating-point number, assuming that the user is familiar with floating-point representations.
The user can download Modscan or Modscan32 from WinTECH Software’s website: . Modscan and Modscan32 can read registers, coils, etc., from a PLC across an Ethernet connection. The user may also be interested in Modsim or Modsim32, available on the same web site. Modsim and Modsim32 simulate a PLC device.
Appendix G:
Differences between Versions 2.x and 3.x of the Interface
• The data conversion options for SquareRoot of 1 and 2 have been changed for output tags. The previous conversions are shown in bold in the following table:
|SquareRoot=1 |Two-step operation for input tags: |
|Convers(0 and |Value = (Value)0.5 |
|Convers(1 |Value = [ (Value - InstZero)/ Convers ] * Span + Zero |
| |Two-step operation for output tags: |
| |Value = (Value)0.5 |
| |Value = [ (Value - Zero)/Span] *Convers + InstZero |
|SquareRoot=2 |Two-step operation for input tags: |
|Convers(0 or |Value = (Value)2 |
|Convers(1 |Value = [ (Value - InstZero)/ Convers ] * Span + Zero |
| |Two-step operation for output tags: |
| |Value = (Value)2 |
| |Value = [ (Value - Zero)/Span] *Convers + InstZero |
• Although serial-based communication is not officially supported for the Modbus Ethernet interface, serial-based communication can be selected by setting /net=none on the command line. If serial-based Modbus communication is selected (/net=none), the InstrumentTag field can now be used to assign a serial port individually to each PI Point. This allows multiple serial ports to be accessed by a single implementation of the interface. The /dn parameter overrides the serial port that is specified in the InstrumentTag field.
• Version 3.x supports TCP/IP-based Modbus communication. The IP address of the PLC is assigned in the InstrumentTag field.
• Version 3.x does not officially support serial-based communication or Modbus Plus communication.
Appendix H :
PLC Exception Responses
Exception responses are returned to the interface from the PLC when there is an operational or programming error associated with a command from the interface. A list of possible exception response codes is shown below.
01 Illegal function
02 Illegal data address
03 Illegal data value
04 Failure in associated device
05 Acknowledge
06 Busy, rejected message
07 NAK-Negative Acknowledgment
08. Memory parity error
0A GATEWAY PATH UNAVAILABLE
Specialized use in conjunction with Modbus Plus gateways, indicates that the gateway was unable to allocate a Modbus Plus PATH to use to process the request. Usually means that the gateway is mis-configured.
0B GATEWAY TARGET DEVICE FAILED TO RESPOND
Specialized use in conjunction with Modbus Plus gateways, indicates that no response was obtained from the target device. Usually means that the device is not present on the network.
Revision History
|Date |Author |Comments |
|26-Jun-98 |GMatzen |Created using Modbus 2.x manual as a template |
|4-Dec-98 |GMatzen |Eliminated all referenced to running the interface on VMS and stated |
| | |throughout this manual that version 3.x of the interface should not be used |
| | |for serial-based communication or Modbus Plus communication. |
|18-Apr-00 |GMatzen |Since serial-based communication and modbus plus communication is not |
| | |officially supported for this interface, the configuration details for these |
| | |communication modes have been eliminated from this manual. The manual has |
| | |been streamlined to focus only on Modbus Ethernet communication. |
|17-Oct-00 |GMatzen |The Modbus interface can now read string data into string tags. The Modbus |
| | |interface now supports sub-second scan classes. |
|30-May-02 |HBeeson |Added ICU Control documentation (3.1x, doc rev A) |
|25-Jul-03 |GMatzen |Documented data type 11. |
|28-Aug-03 |Chrys |Rev B: Added Windows 2000 / XP; changed title of manual; fixed headers & |
| | |footers |
|7-Jul-04 |Chrys |Version 3.25 – 3.26.0.1 Rev A: fixed version # on title page; added checklist,|
| | |digital states, standard install, performance points, i/o rates, interface |
| | |node clock, security; reorganized command-line parameters; changed name from |
| | |modbus.exe to modbusE.exe so ICU control is picked up; reorganized appendices;|
| | |fixed headers & footers |
|9-Jul-04 |Chrys |Version 3.26.0.1 – 3.26.0.2 Rev A: Changed applicable versions on title page. |
|21-Jul-04 |GMatzen |Added example string tag configuration. Changed Appendix E from “Supported |
| | |PLCs” to “PLC Notes”. |
|12-Aug-04 |GMatzen |Added /polldelay, /hcp, and /writedelay documentation. |
|16-Aug-04 |GMatzen |Changed section on manual installation of services to discuss serviceid. |
|16-Aug-04 |GMatzen |Additional changes to the manual service installation section. |
|16-Aug-04 |GMatzen |Added changes from MPK. |
|16-Aug-04 |GMatzen |The manual did not state that float64 points were supported. |
|17-Aug-04 |MKelly |Added section on Configuring the interface with PI ICU |
|7-Sep-04 |GMatzen |Added documentation for data type 16 for reading IEEE double precision floats.|
|8-Sep-04 |GMatzen |Added documentation for data type 12 for reading 16-digit BCDs. |
|29-Nov-04 |GMatzen |Clarified that “destination index” and “unit identifier” are synonymous for |
| | |the location2 attribute. |
|16-Dec-04 |GMatzen |Added documentation for the /requestlen command line parameter, which is |
| | |supported as of modbus version 3.27.0.1. |
|3-Jan-05 |GMatzen |The /net=tcp command line parameter is no longer needed. Changed the document |
| | |accordingly. |
|9-Mar-05 |GMatzen |Sub-second scan classes and timestamps are supported. Fixed document. |
|27-Apr-05 |MKelly |Fixed copyright page, TOC, headers and footers, section breaks. Added three |
| | |support features from latest manual skeleton which were missing. Modified |
| | |sample batch file to add missing parameters and removed /net=TCP. Modified |
| | |sample data access template. Added new screenshots for ICU section. |
|2-May-05 |GMatzen |The sample command line should not include /pisdk=1. The /ec parameter |
| | |contained extra information that was not appropriate. |
|3-May-05 |GMatzen |Corrected the manual. As of version 3.26.0.8 of the interface, the maximum |
| | |/to is 300 seconds. |
|17-Nov-05 |Janelle |Version 3.27.0.5, Rev A: updated formatting, alphabetized command line |
| | |parameter section, reordered PI Point configuration section, fixed headers and|
| | |footers, fixed spelling errors. |
|17-Nov-05 |GMatzen |Version 2.37.0.5, Rev B: updated serviceid information, removed = sign from |
| | |syntax. |
|29-Nov-05 |Chrys |Version 2.37.0.5, Rev C: Updated TOC to use hyperlinks; fixed some headings; |
| | |formatting |
|27-Mar-06 |Janelle |Version 3.27.0.6, Rev A: Updated headers and footers, updated manual to |
| | |reflect current standards. Removed mention of NT4 as a supported platform. |
|28-Mar-06 |GMatzen |Version 3.27.0.6, Rev B: Added diagram of hardware connection, made |
| | |clarifications. |
|30-Mar-06 |Janelle |Version 3.27.0.6, Rev C: updated the sample bat file |
|4-Apr-06 |MKelly |Version 3.27.0.6, Rev D: Fixed header and footers, updated screenshot for ICU |
| | |section. Miscellaneous formatting changes. |
| | | |
| | | |
| | | |
| | | |
-----------------------
Status of the ICU
Status of the Interface Service
Service installed or uninstalled
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.
Related searches
- ethernet cable for tv hookup
- ethernet to usb c adapter
- ethernet wifi password
- ethernet connection problem
- rename ethernet connection
- windows 10 rename ethernet network
- rename ethernet name
- ethernet name is incorrect
- rename ethernet network windows 10
- rename ethernet connection windows 10
- computer says ethernet not connected
- ethernet connection problems windows 10