Modbus TCP Client CSV Files

From Control Solutions IoTServer Documentation
Revision as of 15:02, 9 April 2019 by Jimhogenson (talk | contribs)
Jump to navigation Jump to search

Modbus TCP Client CSV Files

A CSV file may be imported to configure various aspects of the IoTServer (or Babel Buster gateway). A single CSV file may contain multiple sections. When a file including an “Objects” section is imported by the Data Engine, local objects will be configured. When a file including one or more “Modbus” sections is imported by an instance of the Modbus Engine, Modbus gateway functionality will be configured. The same Modbus file may be imported by a Modbus Client or Modbus Server, and either RTU or TCP, and only those sections of interest to that Modbus function will be imported. The CSV file may also contain one or more SNMP sections, and so forth.

A section begins when the word “Begin” appears in the first column of a line. All lines up to and including a line that begins with the word “End” will be taken to be part of that section.

The line immediately following the “Begin” line must be a header line. A Header line is one which labels the columns of data that will follow the Header line.

All lines following the Header line are data lines that are expected to contain the same number of columns as the Header line, and whose contents are defined by the labels found in each column of the Header line.

Labels in the section Begin and End lines, and labels in the Header line are NOT case sensitive and will be interpreted equally whether upper case, lower case, or some combination of both (for readability).

Labels may NOT contain embedded spaces. A label is terminated by a comma, line-end, or space. Labels may not be encapsulated in quote characters; however, data content in data lines may be encapsulated in quote characters and may contain embedded spaces or blanks if quoted.

Some labels in the Header line may be considered optional. The minimum required columns are indicated in the definition of each data section.

Columns in the Header line do not have to follow any particular order. They may be rearranged to the user’s liking. The only restriction is that data in subsequent data lines must match up with the labels placed in the Header line. Data lines may contain fewer columns than the Header line, but may not contain more. Data columns that the user wishes to deliberately omit, but omit between included columns, should be indicated by place holder commas (which will simply appear as blank cells in a spread sheet program).

A Begin line will contain three columns:
Column 1: BEGIN
Column 2: Function as noted below
Column 3: Sub-function as noted in definition of the Function.

Functions may be any of the following (with this listed expanded from time to time):

  • LOCALDATA
  • MODBUS
  • SNMP

Sub-functions:

MODBUS

  • DEVICES
  • READMAPS
  • WRITEMAPS
  • SERVERMAPS
  • SERVERREMAPS

NOTE: A Modbus CSV file may contain both client and server sections as the respective functionality will select sections relevant to its purpose. It should also be noted that the same application, csiModbusEngine, can function as both client and server (master and slave).

MODBUS Client CSV Example

The following illustrates a valid Modbus TCP Client CSV configuration file. The DEVICES, READMAPS, and WRITEMAPS sections of a CSV file will be processed when the Modbus Engine is operating as a Client. Server sections (see later section) will only be processed by an instance of a Modbus Server, and the server will skip over the Client sections illustrated here.

A valid Modbus RTU Client (Master) CSV configuration file would look largely the same, except there is no DEVICES section in a Modbus RTU client. The other minor variation is that “Device,Unit” in the read/write maps are replaced with “Slave”.

Begin,Modbus,Devices
Number,RemoteIP,Port,PollTime,Timeout,Name
1,192.168.1.135,502,2,2,SPX
End
Begin,Modbus,ReadMaps
Device,RegType,RegAddr,RegFormat,RegSize,DestObj,PollTime
1,Hold,0,Int,1,1,5
1,Hold,1,Int,1,2,5
1,Hold,2,Int,1,3,5
End
Begin,Modbus,WriteMaps
SourceObj,Device,RegType,RegAddr,RegFormat,RegSize,PollTime
4,1,Hold,3,Int,1,10
5,1,Hold,4,Int,1,10
End

MODBUS (TCP client) DEVICES Section

The DEVICES section is only processed by an instance of the Modbus Engine that is running as a TCP client. An RTU client will not reference TCP devices. RTU devices are referenced simply by slave address included in the read and write maps. RTU port settings are not represented as CSV since there is only a single instance which may be set via the web UI.

Number – Device number that will be reference in read and write maps.

RemoteIP – The IP address in “a.b.c.d” form that the TCP client will attempt to connect to for read and write maps referencing this device number.

Port – The port number that should be opened at the remote IP address given. Port number will default to 502 if not given or set to zero.

Unit – An optional unit number that will be used when connecting to this remote TCP device. If none is given or is set to zero, then unit 1 will be used.

PollTime – The default poll time that will be used if none is given explicitly in individual read and write maps.

Timeout – The amount of time that the client should wait before flagging the attempted read or write with a “no response” error.

Name – Arbitrary name for this device, used only as a reference in the web UI.

MODBUS (client/master) READMAPS Section

Device – (REQUIRED if TCP) – Device number from the TCP Device list that should be accessed for this read attempt on a TCP network.

Unit – (TCP only) – Unit number to be included in the TCP request, will default to 1 if not given or is set to zero.

Slave – (REQUIRED if RTU) – Slave address that should be transmitted in the read request made on an RTU network.

RegType – Modbus register type from following table, will default to “HOLD” if omitted. The labels must be entered exactly as depicted in the table.

Label Modbus Register type
“none” No register defined
“Coil” Coil
“Disc” Discrete Input
“Input” Input Register
“Hold” Holding Register

RegAddr – (REQUIRED if MODICON not used) – Raw 0-indexed address of the register to be read. IMPORTANT: If manufacturer’s documentation indicates register 40001, DO NOT enter 40001 for RegAddr. This number is short-hand for holding register 1, and its address is zero. Therefore, if you see 40001, select “Hold” for RegType, and enter 0 for RegAddr.

Modicon – (In lieu of RegType, RegAddr) – If one wishes to use Modicon notation, i.e., enter 40001 when the manufacturer’s documentation says 40001, then OMIT RegType AND RegAddr, and use the Modicon label instead. Both standard and extended Modicon are recognized. However, you cannot use both Modicon and RegType/RegAddr in the same section. When Modicon is used, the RegType and RegAddr columns will be generated internally based on the Modicon number given. Modicon is only available for Import. On export, RegType and RegAddr will be used (Modicon notation is not recognized by the Modbus protocol standard even though widely used as a defacto stanard).

RegFormat – Format of the data contained in the Modbus register(s), not used by the protocol, but used by the gateway to interpret what the raw increments of 1 or 16 bits should mean. Select format from the following table.

Format Label Format description
“None” No format defined
“Bit” Single bit, used ONLY for RegType Coil or Disc
“Int” Integer (size and whether signed are defined by labels below)
“Real” Floating point (single or double precision)
“Char” Character string with 2 ASCII characters per register
“Mod10” Mod10 format, can be 2, 3, or 4-register, specific to Schneider Electric meters

RegSize – Register size refers to the number of consecutive input or holding registers should be read for a value greater than 16 bits. A 16-bit value would have size of 1, a 32-bit value would have size of 2, and a 64-bit value would have size of 4. Single precision Real (32-bit IEEE 754 floating point) would be size 2, and double precision Real (64-bit IEEE 754 floating point) would be size 4. If format is Mod10, then valid sizes are 2, 3, or 4 – check manufacturer’s documentation if Mod10 is noted. Register “size” for a character string will be character count divided by 2 (plus 1 of string length is an odd number). RegSize is not used for Coil or Disc types.

Unsigned – Indicate “Y” if unsigned, or “N” if signed. Defaults to signed integer. Has no effect on RegFormat other than Int.

LittleEnd – Used when RegSize is greater than 1 to indicate what order the registers should be interpreted in. Enter “Y” to indicate that the lowest numbered register contains the least significant portion of data. Enter “N” or omit to indicate that the lowest numbered register contains the most significant portion of data. Although Modbus protocol itself is not inherently “Little Endian”, many devices operate that way due to Intel processors being inherently Little Endian. Modbus protocol does not stipulate what the register order should be when multiple registers are treated as a single data entity. Therefore, the user is required to pay attention to this.

Mask – A bit mask given as a 4-digit or 8-digit hexadecimal value, if non-zero (Mask operation skipped if mask value is zero, or register format is not Int). When the data of interest is a single bit, or bit field less than the full register width, the Mask is used. When the Modbus register is read, its data is bit-wise ANDed with the Mask, then right justified so that the least significant mask bit becomes the least significant data bit. The result is then placed in the local data object selected by the read map.

Scale – Register content is multiplied by this value, if non-zero, before being placed into the local object.

Offset – This value is added to the register content (after being multiplied by scale) before being placed into the local object.

NOTE: The order of operation is as follows: (1) read Modbus register; (2) apply mask if applicable; (3) apply scale if non-zero; (4) apply offset. Result is then placed in local object.

DestObj – (REQUIRED) – Local object number that the result of the Modbus read operation should be placed into.

PollTime – Poll time in seconds (can be fractional). The sets the rate at which the remote Modbus register will be read. This poll time is not guaranteed to be met. Polling is done in round-robin fashion. In a very busy system, more than this time may expire before the next poll. If less than this time has expired, then the system will wait this amount of time until polling again.

DefValue – Provides the default value that the local object should be set to in the event the FailCount is exceeded.

FailCount – Optional, provides a count of read failures, if non-zero, that can occur before the local object will be set to the default value given in this map. If zero, the default value will never be applied. If 1, then the default value will be applied upon the first failure (probably not recommended), and so on. The count is reset by a successful read.

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

IndexVal – Optional, used in conjunction with IndexObj (see note above).

MODBUS (client/master) WRITEMAPS Section

SourceObj – Specifies the local object number that contains the data that should be sent by this write map.

Scale – Provides a scale factor if non-zero (has the effect of being 1 if zero). Data to be written is retrieved from the local object and then multiplied by this scale factor before being sent to the remote Modbus device. Applies to numeric values and numeric local objects only.

Offset – Provides an offset to work in conjunction with scale factor. This value is added to the value retrieved from the local object (after being multiplied by scale) before being sent to the remote Modbus device. Applies to numeric values and numeric local objects only.

Mask – A bit mask given as a 4-digit or 8-digit hexadecimal value, if non-zero (Mask operation skipped if mask value is zero, or register format is not Int). When the data of interest is a single bit, or bit field less than the full register width, the Mask is used. The process used in a read operation is reversed here. First, the mask is right justified so that the least significant “1” bit is in the least significant data position. That mask is then logically ANDed with the data found in the local object. The result is then left justified back into the position originally indicated by the mask. This value is now ready to be written to the Modbus register, pending any additional operation such as the Fill mask.

Fill – An additional bit mask given as a 4-digit or 8-digit hexadecimal value. This mask is logically ORed with the result of the Mask operation before the final result is written to the Modbus register. The Fill mask has the effect of making sure certain bits in the register are always set.

NOTE: The order of operation is as follows, operating on data retrieved from the local object: (1) apply scale if nonzero; (2) apply offset; (3) apply mask if applicable; (4) apply fill if applicable; (5) write to Modbus register.

Device – (REQUIRED if TCP) – Device number from the TCP Device list that should be accessed for this write attempt on a TCP network.

Unit – (TCP only) – Unit number to be included in the TCP request, will default to 1 if not given or is set to zero.

Slave – (REQUIRED if RTU) – Slave address that should be transmitted in the read request made on an RTU network.

RegType – Modbus register type from following table, will default to “HOLD” if omitted. The labels must be entered exactly as depicted in the table.

Label Modbus Register type
“none” No register defined
“Coil” Coil
“Disc” Discrete Input
“Input” Input Register
“Hold” Holding Register

RegAddr – (REQUIRED if MODICON not used) – Raw 0-indexed address of the register to be read. IMPORTANT: If manufacturer’s documentation indicates register 40001, DO NOT enter 40001 for RegAddr. This number is short-hand for holding register 1, and its address is zero. Therefore, if you see 40001, select “Hold” for RegType, and enter 0 for RegAddr.

Modicon – (In lieu of RegType, RegAddr) – If one wishes to use Modicon notation, i.e., enter 40001 when the manufacturer’s documentation says 40001, then OMIT RegType AND RegAddr, and use the Modicon label instead. Both standard and extended Modicon are recognized. However, you cannot use both Modicon and RegType/RegAddr in the same section. When Modicon is used, the RegType and RegAddr columns will be generated internally based on the Modicon number given. Modicon is only available for Import. On export, RegType and RegAddr will be used (Modicon notation is not recognized by the Modbus protocol standard even though widely used as a defacto stanard).

RegFormat – Format of the data contained in the Modbus register(s), not used by the protocol, but used by the gateway to interpret what the raw increments of 1 or 16 bits should mean. Select format from the following table.

Format Label Format description
“None” No format defined
“Bit” Single bit, used ONLY for RegType Coil or Disc
“Int” Integer (size and whether signed are defined by labels below)
“Real” Floating point (single or double precision)
“Char” Character string with 2 ASCII characters per register
“Mod10” Mod10 format, can be 2, 3, or 4-register, specific to Schneider Electric meters


RegSize – Register size refers to the number of consecutive input or holding registers should be read for a value greater than 16 bits. A 16-bit value would have size of 1, a 32-bit value would have size of 2, and a 64-bit value would have size of 4. Single precision Real (32-bit IEEE 754 floating point) would be size 2, and double precision Real (64-bit IEEE 754 floating point) would be size 4. If format is Mod10, then valid sizes are 2, 3, or 4 – check manufacturer’s documentation if Mod10 is noted. Register “size” for a character string will be character count divided by 2 (plus 1 of string length is an odd number). RegSize is not used for Coil or Disc types.

UseFC56 – Enter “Y” to force single register writes to use Modbus function 5 to write a single coil, or function 6 to write a single holding register. Function codes will default to “write multiple” function codes 15 and 16 instead of 5 and 6 respectively if “N” is entered or this column is omitted.

Unsigned – Indicate “Y” if unsigned, or “N” if signed. Defaults to signed integer. Has no effect on RegFormat other than Int.

LittleEnd – Used when RegSize is greater than 1 to indicate what order the registers should be interpreted in. Enter “Y” to indicate that the lowest numbered register contains the least significant portion of data. Enter “N” or omit to indicate that the lowest numbered register contains the most significant portion of data. Although Modbus protocol itself is not inherently “Little Endian”, many devices operate that way due to Intel processors being inherently Little Endian. Modbus protocol does not stipulate what the register order should be when multiple registers are treated as a single data entity. Therefore, the user is required to pay attention to this.

SendPeriodic – Set to “N” to disable, or “Y” to enable periodic writing of the Modbus register at the poll rate given by PollTime.

PollTime – Poll time in seconds, can be fractional. This poll time is not guaranteed to be met. Polling is done in round-robin fashion. In a very busy system, more than this time may expire before the next poll. If less than this time has expired, then the system will wait this amount of time until polling again. The sets the rate at which the remote Modbus register will bewritten, provided “SendPeriodic” has been enabled. This poll time will be disregarded if SendPeriodic is not enabled.

SendMaxQuiet – Set to “N” to disable or “Y” to enable the MaxQuietTime feature. If disabled, the MaxQuietTime will be disregarded.

MaxQuietTime – “Max Quiet” time in seconds, can be fractional. If the Modbus register has not been written either as a result of poll timing or value changing by delta within this time period, then write request will be made anyway. This specifies the maximum amount of time that should expire without any write to the Modbus register for any reason.

SendOnDelta – Set to “N” to disable, or “Y” to enable the “send on delta” feature where Modbus writes are made based on changes in the local object value (see delta below).

Delta – Specifies the margin by which the local object value should change before sending another Modbus write request to the remote Modbus device. Once the changed value has been sent, the new local value is retained for future comparison in determining subsequent additional change. The delta value is disregarded if SendOnDelta is not enabled. Note that a delta of zero is treated as a special case: Any update to the local object by any process will result in a new Modbus write request.

MinQuietTime – Time in seconds, can be fractional. This specifies the mínimum amount of time that should elapse between sending of write requests for this write map. The minimum quiet time has the effect of throttling network traffic.

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

IndexVal – Optional, used in conjunction with IndexObj (see note above).