Configuration file parameters

Save PDF

Last UpdatedNov 05, 2024
8 minute read

PI System
PI Interface for Modbus Ethernet PLC 4.3.2
Interfaces

Although the Modbus Interface Configurator should be used to configure the parameters, all of the required and optional parameters are listed in the table below as they are used in the interface configuration file. Since many of the parameters were available in previous versions of the ModbusE interface, the same parameter key names are being used for the familiarity of previous users:

Parameter	Description
/cn=x optional, default: 1	The number specified by the /cn parameter is the number of successive communication failures that must occur before an error is logged and IO Timeout is written to the affected tags. The /cn parameter is useful during serial communication because serial communication frequently fails on 1 attempt but succeeds after an immediate retry. The default value for /cn is 1, and the maximum value is 4.
/debug=# Optional, default: 0	The /debug parameter specifies whether or not to trace I/O for this node. If # is 0 tracing is turned off. If # is 1, the interface will trace all packets sent to or received from this node. The default value of # is 0.
/disabled=# optional	The/disabled parameter defines whether the Ethernet node is disabled or not. If # is 1, the Ethernet node is disabled and the interface does not attempt to scan the node. If # is 0, the node is enabled. The default value of # is 0. Note: An Ethernet node may be enabled or disabled while the interface is running.
/dn=x:p required	The /dn parameter defines the device name (Ethernet node) in which x:p represents the node (e.g. 192.168.70.190:502). x must be a valid IP address or host name and p must be a valid service port in which x is separated from p by a colon. For example, node 192.168.70.190:502 consists of IP address 192.168.70.190 and port 502.
/hcp optional	The /hcp parameter indicates that the standard Modbus Application Protocol (MBAP) header is not used in message packets.
/ialler=x Optional	The /ialler parameter is used to ignore all exceptions and retry the request. x must be 1 to be enabled. Otherwise it will be ignored.
/icrcer=x Optional	The /icrcer parameter is used to ignore all CRC and unknown exceptions and retry the request. x must be 1 to be enabled. Otherwise it will be ignored.
/idevstat=x Optional	The /idevstat parameter is used to ignore some device status changes that may trigger a failover. x must be 1 to be enabled. Otherwise it will be ignored.
/logging=# Optional, Default: 57343	The /logging parameter defines the logging flags and whether logging is turned on. If # is 0 logging is turned off. Otherwise # is the addition of one or more of the logging flag values. The default value of # is 57343 (all logging flags are turned on except for reduced logging).
/lsi=# Optional, Default: 10	The /lsi parameter specifies the log suspension interval of reduced logging for the interface. If reduced logging is enabled # is the interval in seconds that a maximum number of messages (/mpi) will be logged. # must be an integer value between 1 and 1000 seconds. The default value of # is 10 seconds.
/maxrequests=# Optional, Default: 1	The /maxrequests parameter limits the maximum number of simultaneous requests that the interface will send to this node. The interface will send up to this many requests before waiting for a response or timeout. For best performance, set this parameter equal to the value of NumberMaxOfServerTransaction specified in the device's documentation. Note that if there are multiple PLCs at the same IP address, this limit applies to all of them collectively rather than to each individually. The default value of # is 1 request.
/mindelay=# Optional, Default: 0	The /mindelay parameter is used to specify a minimum delay time between requests sent to this node. # is the delay time in milliseconds and must be an integer value of 0 to 10,000 milliseconds. Sometimes it is possible for the ModbusE interface to send commands to a device at a faster rate than the device can handle the messages. The problem is most likely to occur when the same device is scheduled to be scanned from two different scan classes when the scan time coincides for the two scan classes. For example, /f=5,0 and /f=10,0 will coincide every 10 seconds. Typical symptoms of an insufficient /mindelay are I/O Timeouts for the affected tags and log messages indicating that the interface has received exception responses from the device. The default poll delay is 0 milliseconds. The delay should not need to be increased above 100 milliseconds.
/mpi=# Optional, Default: 10	The /mpi parameter specifies the messages per interval of reduced logging for the interface. If reduced logging is enabled # is the maximum number of messages that will be logged during the log suspension interval (/lsi). # must be an integer value between 1 and 1000. The default value of # is 10.
/nodeoffset=# Optional, Default: 0	The /nodeoffset parameter specifies an optional extra offset to add to each address before sending requests to this node. For example, setting /nodeoffset=1 and Location5=16 is equivalent to setting /nodeoffset=0 and Location5=17. Use this parameter to resolve off-by-one problems that might arise for PLCs that expect zero-indexed addresses instead of one-indexed addresses. The value of # must be -1, 0, or 1. The default value of # is 0.
/pcf=# Optional, Default: 0	The /pcf parameter specifies the dynamic run-time configuration flags for the interface. If # is 0 dynamic node configuration is turned off. Otherwise # is the addition of one or more of the logging flag values. The default value of # is 0.
/polldelay=# optional, default: 0	OBSOLETE. Use /mindelay instead. For backwards compatibility, setting /polldelay is still allowed and is equivalent to setting /mindelay. The /polldelay parameter is used to specify a minimum delay time between scans. # is the delay time in milliseconds and must be an integer value of 0 to 10,000 milliseconds. Sometimes it is possible for the ModbusE interface to send commands to a device at a faster rate than the device can handle the messages. The problem is most likely to occur when the same device is scheduled to be scanned from two different scan classes when the scan time coincides for the two scan classes. For example, /f=5,0 and /f=10,0 will coincide every 10 seconds. One possible symptom of an insufficient /polldelay are IO Timeouts reported by the interface. The default poll delay is 0 milliseconds. The delay should not need to be increased above 100 milliseconds.
/rci=# optional, default: 30	The/rci parameter is used to specify the reconnect interval in seconds when a connection fails for TCP/IP communication. Unless the /cn parameter is set to a value greater than 1, the interface will not try to reconnect until the reconnection interval has expired.
/reqts=# optional	The /reqts parameter is used to specify that the timestamp for a tag is set when the value of the tag is requested. If # is 1 the timestamp is set on a request. Otherwise if # not 1 or the /reqts parameter is not used the tag timestamp is set on a response.
/requestlen=# optional, see description for default	The request length for Modbus messages can be adjusted to between 10 and 250 bytes. The default is 100 bytes for function codes 1 and 2 and 200 bytes for the remaining function codes. When the /requestlen parameter is used, the number of bytes that are read by all function codes are the same.
/swap4 optional	This parameter is used only in conjunction with points of data type 4 (see location3 under "PI Point Definition"). Some PLCs store floating points with the high and low bytes swapped from the default order that the ModbusE interface is expecting. If this is the case, the /swap4 parameter will need to be specified as an Ethernet node parameter.
/swap6 optional	This parameter is used only in conjunction with points of data type 6 (see location3 under "PI Point Definition"). This parameter is required to read floating points from Modicon PLCs. Basically, some PLCs store floating points with the high and low bytes swapped from the default order that the ModbusE interface is expecting. If this is the case, the /swap6 parameter will need to be specified as an Ethernet node parameter.
/swap7 optional	This parameter is used only in conjunction with points of data type 7 (see location3 under "PI Point Definition"). Some PLCs store 4-byte integers with the high and low bytes swapped from the default order that the ModbusE interface is expecting. If this is the case, the /swap7 parameter will need to be specified as an Ethernet node parameter.
/swap13 optional	This parameter is used only in conjunction with data type 13 (8-Byte Signed Integer). When the /swap13 parameter is specified, the interface will expect the bytes that are sent from the PLC in a different order than the default order.
/swap15 optional	This parameter is used only in conjunction with data type 15 (8-Byte Unsigned Integer). When the /swap15 parameter is specified, the interface will expect the bytes that are sent from the PLC in a different order than the default order.
/swap16 optional	This parameter is used only in conjunction with data type 16 (double precision 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 optional	This parameter is used in conjunction with data types 101 and higher. These 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=# default: 2 optional	Defines the number of seconds that the interface waits for an answer from a node before a timeout occurs. # is an integer from 1 to 300. The default is 2 seconds. It is not recommended to set the timeout above 10 seconds unless there truly is a need. If the timeout is set unnecessarily high, then the interface will wait for a period of time equal to the product of the /to and /cn parameters every time that the interface tries to read from a node that is offline. This could impede data collection from other nodes that are not experiencing problems.
/tracetag=x optional	The /tracetag parameter specifies the name of a single tag for which more extensive tracing will be written. x must be in the long name form of a valid tag.
/writedelay=# optional, default: 0	OBSOLETE. Use /mindelay instead. For backwards compatibility, setting /writedelay is still allowed and is equivalent to setting /mindelay . The /writedelay parameter is used to specify a minimum delay time between outputs. x is the delay time in milliseconds and must be an integer value of 0 to 10,000 milliseconds. Sometimes it is possible for the ModbusE interface to send commands to a device at a faster rate than the device can handle the messages. The problem is most likely to occur if several outputs occur at the same time. One possible symptom of an insufficient /writedelay are IO Timeouts reported by the interface. The default write delay is 0 milliseconds. The delay should not need to be increased above 100 milliseconds.

Parameter

Description

/cn=x

optional,

default: 1

The number specified by the /cn parameter is the number of successive communication failures that must occur before an error is logged and IO Timeout is written to the affected tags. The /cn parameter is useful during serial communication because serial communication frequently fails on 1 attempt but succeeds after an immediate retry. The default value for /cn is 1, and the maximum value is 4.

/debug=#

Optional,

default: 0

The /debug parameter specifies whether or not to trace I/O for this node. If # is 0 tracing is turned off. If # is 1, the interface will trace all packets sent to or received from this node. The default value of # is 0.

/disabled=#

optional

The/disabled parameter defines whether the Ethernet node is disabled or not.

If # is 1, the Ethernet node is disabled and the interface does not attempt to scan the node.
If # is 0, the node is enabled.

The default value of # is 0.

Note: An Ethernet node may be enabled or disabled while the interface is running.

/dn=x:p

required

The /dn parameter defines the device name (Ethernet node) in which x:p represents the node (e.g. 192.168.70.190:502).

x must be a valid IP address or host name and p must be a valid service port in which x is separated from p by a colon.

For example, node 192.168.70.190:502 consists of IP address 192.168.70.190 and port 502.

/hcp

optional

The /hcp parameter indicates that the standard Modbus Application Protocol (MBAP) header is not used in message packets.

/ialler=x

Optional

The /ialler parameter is used to ignore all exceptions and retry the request. x must be 1 to be enabled. Otherwise it will be ignored.

/icrcer=x

Optional

The /icrcer parameter is used to ignore all CRC and unknown exceptions and retry the request. x must be 1 to be enabled. Otherwise it will be ignored.

/idevstat=x

Optional

The /idevstat parameter is used to ignore some device status changes that may trigger a failover. x must be 1 to be enabled. Otherwise it will be ignored.

/logging=#

Optional,

Default: 57343

The /logging parameter defines the logging flags and whether logging is turned on. If # is 0 logging is turned off. Otherwise # is the addition of one or more of the logging flag values. The default value of # is 57343 (all logging flags are turned on except for reduced logging).

/lsi=#

Optional,

Default: 10

The /lsi parameter specifies the log suspension interval of reduced logging for the interface. If reduced logging is enabled # is the interval in seconds that a maximum number of messages (/mpi) will be logged. # must be an integer value between 1 and 1000 seconds. The default value of # is 10 seconds.

/maxrequests=#

Optional,

Default: 1

The /maxrequests parameter limits the maximum number of simultaneous requests that the interface will send to this node. The interface will send up to this many requests before waiting for a response or timeout. For best performance, set this parameter equal to the value of NumberMaxOfServerTransaction specified in the device's documentation.

Note that if there are multiple PLCs at the same IP address, this limit applies to all of them collectively rather than to each individually.

The default value of # is 1 request.

/mindelay=#

Optional,

Default: 0

The /mindelay parameter is used to specify a minimum delay time between requests sent to this node. # is the delay time in milliseconds and must be an integer value of 0 to 10,000 milliseconds.

Sometimes it is possible for the ModbusE interface to send commands to a device at a faster rate than the device can handle the messages. The problem is most likely to occur when the same device is scheduled to be scanned from two different scan classes when the scan time coincides for the two scan classes. For example, /f=5,0 and /f=10,0 will coincide every 10 seconds.

Typical symptoms of an insufficient /mindelay are I/O Timeouts for the affected tags and log messages indicating that the interface has received exception responses from the device.

The default poll delay is 0 milliseconds. The delay should not need to be increased above 100 milliseconds.

/mpi=#

Optional,

Default: 10

The /mpi parameter specifies the messages per interval of reduced logging for the interface. If reduced logging is enabled # is the maximum number of messages that will be logged during the log suspension interval (/lsi). # must be an integer value between 1 and 1000. The default value of # is 10.

/nodeoffset=#

Optional,

Default: 0

The /nodeoffset parameter specifies an optional extra offset to add to each address before sending requests to this node. For example, setting /nodeoffset=1 and Location5=16 is equivalent to setting /nodeoffset=0 and Location5=17. Use this parameter to resolve off-by-one problems that might arise for PLCs that expect zero-indexed addresses instead of one-indexed addresses.

The value of # must be -1, 0, or 1. The default value of # is 0.

/pcf=#

Optional,

Default: 0

The /pcf parameter specifies the dynamic run-time configuration flags for the interface. If # is 0 dynamic node configuration is turned off. Otherwise # is the addition of one or more of the logging flag values. The default value of # is 0.

/polldelay=#

optional,

default: 0

OBSOLETE. Use /mindelay instead. For backwards compatibility, setting /polldelay is still allowed and is equivalent to setting /mindelay.

The /polldelay parameter is used to specify a minimum delay time between scans. # is the delay time in milliseconds and must be an integer value of 0 to 10,000 milliseconds.

One possible symptom of an insufficient /polldelay are IO Timeouts reported by the interface. The default poll delay is 0 milliseconds. The delay should not need to be increased above 100 milliseconds.

/rci=#

optional,

default: 30

The/rci parameter is used to specify the reconnect interval in seconds when a connection fails for TCP/IP communication. Unless the /cn parameter is set to a value greater than 1, the interface will not try to reconnect until the reconnection interval has expired.

/reqts=#

optional

The /reqts parameter is used to specify that the timestamp for a tag is set when the value of the tag is requested. If # is 1 the timestamp is set on a request. Otherwise if # not 1 or the /reqts parameter is not used the tag timestamp is set on a response.

/requestlen=#

optional,

see description for default

The request length for Modbus messages can be adjusted to between 10 and 250 bytes. The default is 100 bytes for function codes 1 and 2 and 200 bytes for the remaining function codes. When the /requestlen parameter is used, the number of bytes that are read by all function codes are the same.

/swap4

optional

This parameter is used only in conjunction with points of data type 4 (see location3 under "PI Point Definition"). Some PLCs store floating points with the high and low bytes swapped from the default order that the ModbusE interface is expecting. If this is the case, the /swap4 parameter will need to be specified as an Ethernet node parameter.

/swap6

optional

This parameter is used only in conjunction with points of data type 6 (see location3 under "PI Point Definition"). This parameter is required to read floating points from Modicon PLCs. Basically, some PLCs store floating points with the high and low bytes swapped from the default order that the ModbusE interface is expecting. If this is the case, the /swap6 parameter will need to be specified as an Ethernet node parameter.

/swap7

optional

This parameter is used only in conjunction with points of data type 7 (see location3 under "PI Point Definition"). Some PLCs store 4-byte integers with the high and low bytes swapped from the default order that the ModbusE interface is expecting. If this is the case, the /swap7 parameter will need to be specified as an Ethernet node parameter.

/swap13

optional

This parameter is used only in conjunction with data type 13 (8-Byte Signed Integer). When the /swap13 parameter is specified, the interface will expect the bytes that are sent from the PLC in a different order than the default order.

/swap15

optional

This parameter is used only in conjunction with data type 15 (8-Byte Unsigned Integer). When the /swap15 parameter is specified, the interface will expect the bytes that are sent from the PLC in a different order than the default order.

/swap16

optional

This parameter is used only in conjunction with data type 16 (double precision 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

optional

This parameter is used in conjunction with data types 101 and higher. These 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=#

default: 2

optional

Defines the number of seconds that the interface waits for an answer from a node before a timeout occurs. # is an integer from 1 to 300. The default is 2 seconds. It is not recommended to set the timeout above 10 seconds unless there truly is a need. If the timeout is set unnecessarily high, then the interface will wait for a period of time equal to the product of the /to and /cn parameters every time that the interface tries to read from a node that is offline. This could impede data collection from other nodes that are not experiencing problems.

/tracetag=x

optional

The /tracetag parameter specifies the name of a single tag for which more extensive tracing will be written. x must be in the long name form of a valid tag.

/writedelay=#

optional,

default: 0

OBSOLETE. Use /mindelay instead. For backwards compatibility, setting /writedelay is still allowed and is equivalent to setting /mindelay .

The /writedelay parameter is used to specify a minimum delay time between outputs. x is the delay time in milliseconds and must be an integer value of 0 to 10,000 milliseconds.

Sometimes it is possible for the ModbusE interface to send commands to a device at a faster rate than the device can handle the messages. The problem is most likely to occur if several outputs occur at the same time.

One possible symptom of an insufficient /writedelay are IO Timeouts reported by the interface. The default write delay is 0 milliseconds. The delay should not need to be increased above 100 milliseconds.

PI Interface for Modbus Ethernet PLC

Configuration file parameters

Table of Contents

Configuration file parameters

Related Links