Difference between revisions of "Modbus TCP Client XML Files"

From Control Solutions IoTServer Documentation
Jump to navigation Jump to search
 
(3 intermediate revisions by the same user not shown)
Line 6: Line 6:
 
&lt;configuration&gt;<br>
 
&lt;configuration&gt;<br>
  
&lt;modbus_clientdevices&gt;<br>
+
&lt;modbus_client_devices&gt;<br>
 
&lt;dev id="1" ipaddr="192.168.1.87" unit="1" name="BB2-6010"/&gt;<br>
 
&lt;dev id="1" ipaddr="192.168.1.87" unit="1" name="BB2-6010"/&gt;<br>
&lt;/modbus_clientdevices&gt;<br>
+
&lt;/modbus_client_devices&gt;<br>
  
 
&lt;modbus_client_read&gt;<br>
 
&lt;modbus_client_read&gt;<br>
Line 25: Line 25:
  
 
&lt;/configuration&gt;<br>
 
&lt;/configuration&gt;<br>
 +
 +
== Modbus TCP Client &lt;modbus_client_devices&gt; Section ==
 +
 +
'''id=”n”'''  – Specifies the device number that will be referenced in read and write maps. The client uses the device number found in the read or write map to look up the Modbus TCP IP address in this table.
 +
 +
'''ipaddr=”a.b.c.d”'''  – IP address of remote Modbus TCP server (slave).
 +
 +
'''port=”n”'''  – Port number to query on remote Modbus TCP device, defaults to the standard Modbus TCP port 502 if not provided or is zero.
 +
 +
'''unit=”n”'''  – Unit number to include in Modbus TCP query, sometimes used to route queries to multiple RTU devices on the other side of a TCP gateway. Note: This unit number is only a default value; the unit number given in the read or write map (if any) will override this value.
 +
 +
'''rate=”n”'''  – The default poll rate for read or write maps used when no poll time is provided explicitly in the read or write map.
 +
 +
'''timeout=”n”'''  – Timeout for slave/server response. If no reply received in response to a query within this amount of time, the attempt is flagged as a “no response” error.
 +
 +
'''name=”xxx”'''  – A name given for reference purposes only, used on web pages and in XML files, but has no bearing on Modbus protocol activity.
 +
 +
== Modbus TCP Client &lt;modbus_client_read&gt; Section ==
 +
 +
Map Number is implied by order in XML  – Used as a reference in the map list for ordering the maps. Polling is done in round robin fashion in the order of map number.
 +
 +
'''type=”xxx”'''  – Specifies Modbus register type to read. Valid values in XML and are shown below:
 +
 +
{| class="wikitable"
 +
|-
 +
! XML value !! Modbus Register type
 +
|-
 +
| “none” || No register defined
 +
|-
 +
| “coil” || Coil
 +
|-
 +
| “disc” || Discrete Input
 +
|-
 +
| “input” || Input Register
 +
|-
 +
| “hold” || Holding Register
 +
|}
 +
 +
'''addr=”n”''' – Specifies register address to read. Note that this is address starting from zero, not register number starting from one like most Control Solutions gateways. Valid address range is 0..65535. NOTE: The Web UI provides the means to let the user switch between display of addresses (0-indexed), register numbers (1-indexed), or Modicon notation (where number and type are combined into one value).
 +
 +
'''format=”xxx”'''  – Specifies the format in which the Modbus data should be interpreted. Valid formats for XML are shown below:
 +
 +
{| class="wikitable"
 +
|-
 +
! XML value !! Format description
 +
|-
 +
| “none” || No format defined
 +
|-
 +
| “bit” || Single bit (coil, discrete only)
 +
|-
 +
| “int” || Integer (16-, 32-, or 64-bit)
 +
|-
 +
| “real” || Floating point (single or double)
 +
|-
 +
| “char” || ASCII character string
 +
|-
 +
| “mod10” || Schneider Electric Mod10 format
 +
|}
 +
 +
'''size=”n”'''  – Specifies the size of the object in number of Modbus registers. All Modbus registers are either a single bit or 16 bits. It is up to the application to interpret multiple registers as other data sizes, which the client does automatically when configured to read multiple registers. Only certain combinations of data formats and register counts are valid. Note that character strings are defined as a number of registers each holding two ASCII characters.
 +
 +
Valid sizes by register format are as follows:
 +
 +
{| class="wikitable"
 +
|-
 +
! Type !! Number of registers
 +
|-
 +
| Bit || 1
 +
|-
 +
| Integer || 1, 2, 4 (for 16-, 32-, 64-bit)
 +
|-
 +
| Real || 2, 4 (for single, double precision)
 +
|-
 +
| Character || 1..63 (registers - 2 characters per register)
 +
|-
 +
| Mod10 || 2, 3, 4
 +
|}
 +
 +
'''unsigned=”n”'''  – Registers default to being treated as signed when integer. If this attribute value is non-zero, then it will be treated as unsigned.
 +
 +
'''lowfirst=”n”'''  – Specifies “little endian” when value is non-zero. Defaults to “big endian” if omitted or value is zero. In “little endian” mode, the least significant data is in the first or lowest numbered Modbus register. In “big endian” mode, the most significant data is in the first or lowest numbered Modbus register. This only applies to multiple-register non-character data entities (e.g. 32-bit integer). Character strings are always stored with the first character in the string located in the first or lowest numbered Modbus register.
 +
 +
'''dev=”n”'''  – Specifies the device to look up in the Modbus TCP device table to obtain the IP address, port, etc, of the Modbus server/slave to query. (Not included in Modbus RTU XML files.)
 +
 +
'''unit=”n”''' – Specifies the unit number to include in the TCP query (same as slave for RTU).
 +
 +
'''scale=”n”'''  – Scale factor – data read from a Modbus device is multiplied by the scale factor, then offset is added, to produce a final result that is placed into the local data object. If “mask” is also provided, mask is applied before scale and offset.
 +
 +
'''offset=”n”'''  – Offset – added to data read from Modbus device (see scale).
 +
 +
'''poll=”n”'''  – Poll time in seconds determines how often this remote Modbus register will be read.
 +
 +
'''objnum=”n”'''  – Specifies the local object where the result of the Modbus read should be placed.
 +
 +
'''mask=”n”'''  – Optional, and if non-zero, then the data received from the remote Modbus device is bitwise AND-ed with this bit mask, and then shifted right so that the least significant bit in the resulting value is the least significant bit retained by the mask. Note that mask is only valid when the Modbus register format is integer.
 +
 +
'''default=”n”'''  – Used in conjunction with failCount, if successive read attempts fail, the local object will be set to this default value.
 +
 +
'''maxfail=”n”'''  – Optional, specifies the number of read failures (if non-zero) required before the local object will be set to the default value. If set to zero, then the local object will always retain the most recently received data value, if any, regardless of how old it is.
 +
 +
'''indexobj=”n”'''  – Optional, allows for selectively enabling this read operation. If an index object (local object number) is given, and its value matches the indexValue, then this read operation will take place. If an indexObject is given but the local object’s value does not match the indexValue, then this read operation will be skipped.
 +
 +
'''indexval=”n”'''  – Optional, used in conjunction with indexObject (see note above).
 +
 +
== Modbus TCP Client &lt;modbus_client_write&gt; Section ==
 +
 +
Map Number is implied by order in XML  – Used as a reference in the map list for ordering the maps. Polling is done in round robin fashion in the order of map number.
 +
 +
'''type=”xxx”'''  – Specifies Modbus register type to read. Valid values in XML are shown below:
 +
 +
{| class="wikitable"
 +
|-
 +
! XML value !! Modbus Register type
 +
|-
 +
| “none” || No register defined
 +
|-
 +
| “coil” || Coil
 +
|-
 +
| “disc” || Discrete Input
 +
|-
 +
| “input” || Input Register
 +
|-
 +
| “hold” || Holding Register
 +
|}
 +
 +
'''fc56=”n”'''  – Specifies, if non-zero, that Modbus function codes 5 and 6 should be used instead of the default 15 and 16 for writing coils and holding registers (single versus multiple).
 +
 +
'''addr=”n”'''  – Specifies register address to read. Note that this is address starting from zero, not register number starting from one like most Control Solutions gateways. Valid address range is 0..65535. NOTE: The Web UI should provide the means to let the user switch between display of addresses (0-indexed), register numbers (1-indexed), or Modicon notation (where number and type are combined into one value).
 +
 +
'''format=”xxx”'''  – Specifies the format in which the Modbus data should be interpreted. Valid formats for XML are shown below:
 +
 +
{| class="wikitable"
 +
|-
 +
! XML value !! Format description
 +
|-
 +
| “none” || No format defined
 +
|-
 +
| “bit” || Single bit (coil, discrete only)
 +
|-
 +
| “int” || Integer (16-, 32-, or 64-bit)
 +
|-
 +
| “real” || Floating point (single or double)
 +
|-
 +
| “char” || ASCII character string
 +
|-
 +
| “mod10” || Schneider Electric Mod10 format
 +
|}
 +
 +
 +
'''size=”n”'''  – Specifies the size of the object in number of Modbus registers. All Modbus registers are either a single bit or 16 bits. It is up to the application to interpret multiple registers as other data sizes, which the client does automatically when configured to write multiple registers. Only certain combinations of data formats and register counts are valid. Note that character strings are defined as a number of registers each holding two ASCII characters.
 +
 +
Valid sizes by register format are as follows:
 +
 +
{| class="wikitable"
 +
|-
 +
! Type !! Number of registers
 +
|-
 +
| Bit || 1
 +
|-
 +
| Integer || 1, 2, 4 (for 16-, 32-, 64-bit)
 +
|-
 +
| Real || 2, 4 (for single, double precision)
 +
|-
 +
| Character || 1..63 (registers - 2 characters per register)
 +
|-
 +
| Mod10 || 2, 3, 4
 +
|}
 +
 +
'''unsigned=”n”'''  – Registers default to being treated as signed when integer. If this attribute value is non-zero, then it will be treated as unsigned.
 +
 +
'''lowfirst=”n”'''  – Specifies “little endian” when value is non-zero. Defaults to “big endian” if omitted or value is zero. In “little endian” mode, the least significant data is in the first or lowest numbered Modbus register. In “big endian” mode, the most significant data is in the first or lowest numbered Modbus register. This only applies to multiple-register non-character data entities (e.g. 32-bit integer). Character strings are always stored with the first character in the string located in the first or lowest numbered Modbus register.
 +
 +
'''dev=”n”''' – Specifies the device to look up in the Modbus TCP device table to obtain the IP address, port, etc, of the Modbus server/slave to query. (Not included in Modbus RTU XML files.)
 +
 +
'''unit=”n”'''  – Specifies the unit number to include in the TCP query (same as slave for RTU).
 +
 +
'''scale=”n”'''  – Scale factor – data from the local object is first multiplied by the scale factor, then offset is added, to produce the register content written to the remote Modbus device. If “mask” and/or “fill” are also provided, mask and fill are applied after scale and offset (opposite order compared to read operation).
 +
 +
'''offset=”n”'''  – Offset – added to data to be written to Modbus device (see scale).
 +
 +
'''poll=”n”'''  – Poll time in seconds specifies how often this Modbus register will be written, if periodic polling is enabled. Writing only when the local object changes is an option, in which case the poll time is disregarded.
 +
 +
'''objnum=”n”'''  – Specifies the local object that is the source of data to be written to the remote Modbus device.
 +
 +
'''mask=”n”'''  – Optional, if non-zero, then the data to be written to Modbus is shifted into the position marked by bits set in the mask, and the data is then bitwise AND-ed with the mask. If fill is also provided, then fill is applied after mask, and the result is written to the remote Modbus device. Note that mask is only valid when the Modbus register format is integer.
 +
 +
'''fill=”n”'''  – Optional, and if non-zero, provides a collection of bits that should always be set in the data written to Modbus. The fill is bitwise OR-ed with the data after scale, offset, and mask have been applied. Note that fill is only valid when the Modbus register format is integer.
 +
 +
'''maxquiet=”n”'''  – Specifies the máximum amount of time that may elapse with no transmission of new data to the Modbus slave. This effectively provides a fallback to periodic sending if set to “send on delta” but there is never any change. The Max Quiet Time function is disabled if this attribute is omitted in XML,
 +
 +
'''minquiet=”n”'''  – Specifies the mínimum amount of time that must elapse between transmissions of new data to the Modbus slave. This effectively throttles network traffic when “send on delta” is enabled and the value is changing rapidly. A time of zero effectively disables this feature.
 +
 +
'''delta=”n”'''  – Specifies the amount by which the object value must change before the new value will be transmitted to the Modbus slave. If this attribute is omitted in XML, then the “send on delta” function is disabled. The delta value may be zero, in which case any change is transmitted.
 +
 +
'''indexobj=”n”'''  – Optional, allows for selectively enabling this write operation. If an index object (local object number) is given, and its value matches the indexValue, then this write operation will take place. If an indexObject is given but the local object’s value does not match the indexValue, then this write operation will be skipped.
 +
 +
'''indexval=”n”'''  – Optional, used in conjunction with indexObject (see note above).

Latest revision as of 14:19, 9 April 2019

Modbus TCP Client XML Files

Example XML File

<?xml version="1.0" encoding="ISO-8859-1" ?>
<configuration>

<modbus_client_devices>
<dev id="1" ipaddr="192.168.1.87" unit="1" name="BB2-6010"/>
</modbus_client_devices>

<modbus_client_read>
<map objnum="1" type="hold" addr="0" format="int" size="1" unsigned="1" mask="f" dev="1" poll="2.0"/>
<map objnum="2" type="hold" addr="0" format="int" size="1" unsigned="1" mask="f0" dev="1" poll="2.0"/>
<map objnum="3" type="hold" addr="1" format="int" size="1" dev="1" poll="2.0"/>
</modbus_client_read>

<modbus_client_write>
<map objnum="3" type="hold" addr="2" format="int" size="1" dev="1" poll="2.0"/>
<map objnum="1" type="hold" addr="3" mask="f" format="int" size="1" unsigned="1" dev="1" poll="2.0"/>
<map objnum="2" type="hold" addr="3" mask="f0" fill="100" format="int" size="1" unsigned="1" dev="1" poll="2.0"/>
<map objnum="1" type="hold" addr="4" format="int" size="1" dev="1" poll="2.0"/>
<map objnum="2" type="hold" addr="5" format="int" size="1" dev="1" poll="2.0"/>
</modbus_client_write>

</configuration>

Modbus TCP Client <modbus_client_devices> Section

id=”n” – Specifies the device number that will be referenced in read and write maps. The client uses the device number found in the read or write map to look up the Modbus TCP IP address in this table.

ipaddr=”a.b.c.d” – IP address of remote Modbus TCP server (slave).

port=”n” – Port number to query on remote Modbus TCP device, defaults to the standard Modbus TCP port 502 if not provided or is zero.

unit=”n” – Unit number to include in Modbus TCP query, sometimes used to route queries to multiple RTU devices on the other side of a TCP gateway. Note: This unit number is only a default value; the unit number given in the read or write map (if any) will override this value.

rate=”n” – The default poll rate for read or write maps used when no poll time is provided explicitly in the read or write map.

timeout=”n” – Timeout for slave/server response. If no reply received in response to a query within this amount of time, the attempt is flagged as a “no response” error.

name=”xxx” – A name given for reference purposes only, used on web pages and in XML files, but has no bearing on Modbus protocol activity.

Modbus TCP Client <modbus_client_read> Section

Map Number is implied by order in XML – Used as a reference in the map list for ordering the maps. Polling is done in round robin fashion in the order of map number.

type=”xxx” – Specifies Modbus register type to read. Valid values in XML and are shown below:

XML value Modbus Register type
“none” No register defined
“coil” Coil
“disc” Discrete Input
“input” Input Register
“hold” Holding Register

addr=”n” – Specifies register address to read. Note that this is address starting from zero, not register number starting from one like most Control Solutions gateways. Valid address range is 0..65535. NOTE: The Web UI provides the means to let the user switch between display of addresses (0-indexed), register numbers (1-indexed), or Modicon notation (where number and type are combined into one value).

format=”xxx” – Specifies the format in which the Modbus data should be interpreted. Valid formats for XML are shown below:

XML value Format description
“none” No format defined
“bit” Single bit (coil, discrete only)
“int” Integer (16-, 32-, or 64-bit)
“real” Floating point (single or double)
“char” ASCII character string
“mod10” Schneider Electric Mod10 format

size=”n” – Specifies the size of the object in number of Modbus registers. All Modbus registers are either a single bit or 16 bits. It is up to the application to interpret multiple registers as other data sizes, which the client does automatically when configured to read multiple registers. Only certain combinations of data formats and register counts are valid. Note that character strings are defined as a number of registers each holding two ASCII characters.

Valid sizes by register format are as follows:

Type Number of registers
Bit 1
Integer 1, 2, 4 (for 16-, 32-, 64-bit)
Real 2, 4 (for single, double precision)
Character 1..63 (registers - 2 characters per register)
Mod10 2, 3, 4

unsigned=”n” – Registers default to being treated as signed when integer. If this attribute value is non-zero, then it will be treated as unsigned.

lowfirst=”n” – Specifies “little endian” when value is non-zero. Defaults to “big endian” if omitted or value is zero. In “little endian” mode, the least significant data is in the first or lowest numbered Modbus register. In “big endian” mode, the most significant data is in the first or lowest numbered Modbus register. This only applies to multiple-register non-character data entities (e.g. 32-bit integer). Character strings are always stored with the first character in the string located in the first or lowest numbered Modbus register.

dev=”n” – Specifies the device to look up in the Modbus TCP device table to obtain the IP address, port, etc, of the Modbus server/slave to query. (Not included in Modbus RTU XML files.)

unit=”n” – Specifies the unit number to include in the TCP query (same as slave for RTU).

scale=”n” – Scale factor – data read from a Modbus device is multiplied by the scale factor, then offset is added, to produce a final result that is placed into the local data object. If “mask” is also provided, mask is applied before scale and offset.

offset=”n” – Offset – added to data read from Modbus device (see scale).

poll=”n” – Poll time in seconds determines how often this remote Modbus register will be read.

objnum=”n” – Specifies the local object where the result of the Modbus read should be placed.

mask=”n” – Optional, and if non-zero, then the data received from the remote Modbus device is bitwise AND-ed with this bit mask, and then shifted right so that the least significant bit in the resulting value is the least significant bit retained by the mask. Note that mask is only valid when the Modbus register format is integer.

default=”n” – Used in conjunction with failCount, if successive read attempts fail, the local object will be set to this default value.

maxfail=”n” – Optional, specifies the number of read failures (if non-zero) required before the local object will be set to the default value. If set to zero, then the local object will always retain the most recently received data value, if any, regardless of how old it is.

indexobj=”n” – Optional, allows for selectively enabling this read operation. If an index object (local object number) is given, and its value matches the indexValue, then this read operation will take place. If an indexObject is given but the local object’s value does not match the indexValue, then this read operation will be skipped.

indexval=”n” – Optional, used in conjunction with indexObject (see note above).

Modbus TCP Client <modbus_client_write> Section

Map Number is implied by order in XML – Used as a reference in the map list for ordering the maps. Polling is done in round robin fashion in the order of map number.

type=”xxx” – Specifies Modbus register type to read. Valid values in XML are shown below:

XML value Modbus Register type
“none” No register defined
“coil” Coil
“disc” Discrete Input
“input” Input Register
“hold” Holding Register

fc56=”n” – Specifies, if non-zero, that Modbus function codes 5 and 6 should be used instead of the default 15 and 16 for writing coils and holding registers (single versus multiple).

addr=”n” – Specifies register address to read. Note that this is address starting from zero, not register number starting from one like most Control Solutions gateways. Valid address range is 0..65535. NOTE: The Web UI should provide the means to let the user switch between display of addresses (0-indexed), register numbers (1-indexed), or Modicon notation (where number and type are combined into one value).

format=”xxx” – Specifies the format in which the Modbus data should be interpreted. Valid formats for XML are shown below:

XML value Format description
“none” No format defined
“bit” Single bit (coil, discrete only)
“int” Integer (16-, 32-, or 64-bit)
“real” Floating point (single or double)
“char” ASCII character string
“mod10” Schneider Electric Mod10 format


size=”n” – Specifies the size of the object in number of Modbus registers. All Modbus registers are either a single bit or 16 bits. It is up to the application to interpret multiple registers as other data sizes, which the client does automatically when configured to write multiple registers. Only certain combinations of data formats and register counts are valid. Note that character strings are defined as a number of registers each holding two ASCII characters.

Valid sizes by register format are as follows:

Type Number of registers
Bit 1
Integer 1, 2, 4 (for 16-, 32-, 64-bit)
Real 2, 4 (for single, double precision)
Character 1..63 (registers - 2 characters per register)
Mod10 2, 3, 4

unsigned=”n” – Registers default to being treated as signed when integer. If this attribute value is non-zero, then it will be treated as unsigned.

lowfirst=”n” – Specifies “little endian” when value is non-zero. Defaults to “big endian” if omitted or value is zero. In “little endian” mode, the least significant data is in the first or lowest numbered Modbus register. In “big endian” mode, the most significant data is in the first or lowest numbered Modbus register. This only applies to multiple-register non-character data entities (e.g. 32-bit integer). Character strings are always stored with the first character in the string located in the first or lowest numbered Modbus register.

dev=”n” – Specifies the device to look up in the Modbus TCP device table to obtain the IP address, port, etc, of the Modbus server/slave to query. (Not included in Modbus RTU XML files.)

unit=”n” – Specifies the unit number to include in the TCP query (same as slave for RTU).

scale=”n” – Scale factor – data from the local object is first multiplied by the scale factor, then offset is added, to produce the register content written to the remote Modbus device. If “mask” and/or “fill” are also provided, mask and fill are applied after scale and offset (opposite order compared to read operation).

offset=”n” – Offset – added to data to be written to Modbus device (see scale).

poll=”n” – Poll time in seconds specifies how often this Modbus register will be written, if periodic polling is enabled. Writing only when the local object changes is an option, in which case the poll time is disregarded.

objnum=”n” – Specifies the local object that is the source of data to be written to the remote Modbus device.

mask=”n” – Optional, if non-zero, then the data to be written to Modbus is shifted into the position marked by bits set in the mask, and the data is then bitwise AND-ed with the mask. If fill is also provided, then fill is applied after mask, and the result is written to the remote Modbus device. Note that mask is only valid when the Modbus register format is integer.

fill=”n” – Optional, and if non-zero, provides a collection of bits that should always be set in the data written to Modbus. The fill is bitwise OR-ed with the data after scale, offset, and mask have been applied. Note that fill is only valid when the Modbus register format is integer.

maxquiet=”n” – Specifies the máximum amount of time that may elapse with no transmission of new data to the Modbus slave. This effectively provides a fallback to periodic sending if set to “send on delta” but there is never any change. The Max Quiet Time function is disabled if this attribute is omitted in XML,

minquiet=”n” – Specifies the mínimum amount of time that must elapse between transmissions of new data to the Modbus slave. This effectively throttles network traffic when “send on delta” is enabled and the value is changing rapidly. A time of zero effectively disables this feature.

delta=”n” – Specifies the amount by which the object value must change before the new value will be transmitted to the Modbus slave. If this attribute is omitted in XML, then the “send on delta” function is disabled. The delta value may be zero, in which case any change is transmitted.

indexobj=”n” – Optional, allows for selectively enabling this write operation. If an index object (local object number) is given, and its value matches the indexValue, then this write operation will take place. If an indexObject is given but the local object’s value does not match the indexValue, then this write operation will be skipped.

indexval=”n” – Optional, used in conjunction with indexObject (see note above).