Mode. Modsak can be run in one of three modes. In Master mode, Modsak sends requests to a Modbus slave. In Slave mode, Modsak simulates a Modbus device, responding to requests from Modbus masters. In Monitor mode, Modsak relays messages between a master and a slave, displaying the register values that are transferred. See the section Setup overview for more details.

Slave ID. The Slave ID is what is called the "slave address" in the original Modbus specification, and is called the "unit identifier" in the Modbus/TCP specification. It should be in the range 0 to 255.

A zero slave identifier is used in write requests as a broadcast identifier (each slave that receives the message should store the values supplied in the request, but should not normally send a response). If Modsak is in slave mode and the Slave ID is set to 0, Modsak will act on all requests it receives, regardless of the slave identifier in the request. The serial specification limits the range of slave identifiers to 0 to 247, for no apparent reason. The Modbus/TCP implementation guide suggests that Modbus/TCP slaves that can be uniquely identified by their IP address should use slave identifier 255.

Number of Retries. The Number of Retries field specifies how many times Modsak should retry a request that it has not received a response to.

Response Timeout. The Response Timeout field specifies how long (in milliseconds) Modsak should wait for a response before re-trying the request or reporting a failure.

Request Delay. The Request Delay field is used to insert a time delay after each read or write request when polling and when sending a sequence of commands. This may be used to reduce the load on the slave, and maybe also on the computer running Modsak. The delay is measured in milliseconds. (Also see Pass Delay).

Response Delay. The Response Delay field is used in slave mode and monitor mode to insert a time delay before sending a response to a Modbus request. A delay may be necessary when using RS485 to give the master time to switch from transmitting to receiving. The delay is measured in milliseconds.

Max PDU size. This field specifies the maximum allowable number of bytes in the PDU (Protocol Data Unit) of Modbus messages. In master mode, Modsak will refuse to send any request that exceeds the PDU limit, or whose response would exceed the limit. In slave mode, Modsak will discard any request that exceeds the PDU limit, and will return an "Illegal Data Value" error response to any request that would require a response exceeding the limit. See the note on message size limits for more information.

Enforce Count Limits. The current Modbus specification specifies arbitrary limits on the counts in some Modbus requests (e.g. a maximum of 2000 coils in a Read Coils request). Select this checkbox if you want Modsak to enforce these limits.

Since Modsak can handle non-standard register sizes, count limits for holding and input registers are multiplied by 2 and then interpreted as byte count limits. In master mode, Modsak enforces a count limit by refusing to send any request that exceeds the limit, or whose response would exceed the limit. In slave mode, Modsak enforces a count limit by returning an "Illegal Data Value" error response to any request whose count exceeds the limit. See the note on message size limits for more information.

Strict Checking. Normally Modsak checks that received Modbus messages conform to the current Modbus specification, and rejects them if they do not. Some of these checks are not essential: messages that fail them can still be interpreted correctly. Deselect Strict Checking if you want Modsak to be more tolerant of non-conforming messages.

The checks enabled by the Strict Checking setting are:

Allow Long Messages. Some Modbus messages contain a count of the number of data bytes in the message. This byte-count is in a one-byte field, and so has a maximum value of 255, which limits the quantity of data that can be sent in a single message. The byte-count is actually redundant: it is possible to determine the number of data bytes in a message from the overall size of the message.

If you select Allow Long Messages, Modsak will ignore the byte-count field and determine the number of data bytes from the overall message size, and will set the byte-count to 0 when sending messages containing more than 255 data bytes. If you also increase the Max PDU Size, Modsak will be able to send and receive messages containing more than 255 data bytes.

Sending messages containing more than 255 data bytes is non-standard and not widely supported. It may affect the detection of the end of messages when using the RTU packet type, and may affect the ability of the CRC/LRC check to detect errors. However, it should be reliable when using a socket (TCP or UDP) connection. Note that UDP datagrams are limited in size, so this will limit the size of Modbus messages that can be sent using UDP.

Interface Type. Select Serial for a RS232/485 serial interface. Select TCP Socket for a TCP/IP network interface. Select UDP Socket for a UDP/IP interface (use of UDP for Modbus is non-standard). Note that the Serial option will only be available if you have the Java Communications API package installed (the Help → About window tells you whether it is installed).

Packet Type. You would normally select RTU if you are using a serial interface, and TCP if you are using a socket interface. You may have to use ASCII for some legacy serial interfaces or devices. It is possible to use RTU or ASCII packets over a socket interface - this is non-standard, but can be useful for software testing. It is also possible to use TCP packets over a serial interface, but there is no good reason to do so (and there would be no error-checking of the packets).

EOM Timeout. Enter the maximum delay (in milliseconds) expected within a message. The default value works fine in most situations, but you may need to increase the value if you are using a serial interface (or an operating system) that introduces large delays in the middle of messages.

Responses. When using Modbus RTU or ASCII over a serial interface, a slave should not respond to a broadcast request or to a request for a different slave ID (this is necessary for RS485 multi-drop to work). When using Modbus TCP over a TCP socket interface, the slave/bridge should respond to all requests, including broadcasts and requests to unknown/unreachable slaves (responding to the latter with an exception 10 or 11 response). When using non-standard protocol variants (such as RTU encapsulated in TCP), the behaviour in these situations is not defined. You should select Always responds if you want the Modbus TCP behaviour, or deselect it if you want the serial behaviour.

Host. For an interface to a slave, you should enter the host name or IP address of the slave (or Modbus bridge/gateway).

For an interface to a master, you would normally leave this field empty, which allows connections/requests to be accepted via any network interface. But if you enter a host name or IP address of a network interface on the machine running Modsak, then Modsak will only accept connections/requests via that network interface. For example, if you enter localhost (or 127.0.0.1) then Modsak will only accept connections/requests from processes running on the same machine.

Port. For an interface to a slave, you should enter the port number that Modsak should connect to on the slave host (or Modbus gateway).

For an interface to a master, you should enter the port that Modsak should listen on for connections/requests. The standard Modbus port number is 502, but this is a "privileged" port and you will not be able to listen on this port on a Unix/Linux machine unless you are "superuser". This is not normally advisable, so it's better for testing purposes to use a non-privileged port (above 1023).

Port. Name of the serial port that Modsak should use to talk to the master (for a master interface) or slave (for a slave interface). If (during testing) the connection between the master and slave is between two serial ports that are both on the same machine, then you must obviously use different port names for each. Don't forget to connect the two ports with a cable!

Speed. Speed in bits/second.

Parity. It's usual to use no parity, since the CRC in RTU packets is a good error check on its own, but some devices may require it. The serial specification requires even parity to be the default.

Data Bits. Must be 8 for RTU. Some ASCII devices may require 7 (the serial specification actually specifies 7 for ASCII).

Stop Bits. Usually 1, but some devices may require 2. The serial specification actually specifies 2 stop bits if parity is not being used, but this requirement is normally ignored.

RTS Control. The default setting of High will be OK for most purposes.

Selecting Flow Control will enable hardware flow control ("handshaking") using RTS and CTS. Since Modbus messages are short, flow control is not normally necessary.

Selecting RS485 will use RTS to control a RS232 to RS485 converter: Modsak will raise RTS when it is transmitting data, and lower RTS to receive data. Note that the lowering of RTS may be delayed by the operating system, and this may cause loss of data. For this reason, we recommend the use of RS232-RS485 converters that do not require RTS control.

Little Endian. Modbus is a "big-endian" protocol: that is, the more significant byte of a 16-bit value is sent before the less significant byte. It seems obvious that 32-bit and 64-bit values should also be transferred using big-endian order. However, some manufacturers have chosen to treat 32-bit and 64-bit values as being composed of 16-bit words, and to transfer the words in little-endian order. For example, the 32-bit value 0x12345678 would be transferred as 0x56 0x78 0x12 0x34. You should select the Little Endian checkbox to use this mixed ordering.

Word Registers. Each register in the Modbus protocol holds a single (16-bit) value. The simplest way to extend the protocol to handle 32-bit and 64-bit values is to allow registers that contain these larger values. However, some manufacturers have chosen to keep to the 16-bit register size, and use 2 registers to hold a 32-bit value, and 4 registers to hold a 64-bit value. For example, if a 32-bit value is stored at address 100, then register 100 would hold one half of the value and register 101 would hold the other half of the value. Some devices will actually allow you to access the halves of the value independently; others will only allow accesses that transfer the complete value (thus making address 101 in the example an invalid address).

You should select the Word Registers checkbox to use multiple registers to store large values, and leave the checkbox unselected to use a single register to hold each value. Note that when you use the Word Registers option, Modsak will only allow access to complete values, and you should add definitions only for the first register used for each value (in the above example, you should define register 100, but not register 101).

Word Count. Some Modbus requests (e.g function 3 Read Holding Registers, and function 16 Write Multiple Registers) include a count of how many registers/values are to be transferred. There are three possible interpretations for this count:

In the official Modbus protocol, these three interpretations are equivalent, since all values and all registers are 16-bit. When 32-bit and 64-bit values and/or registers are allowed, the three interpretations become distinct. However, the third interpretation will be equivalent to one or other of the first two, depending on the Word Registers setting, so Modsak only deals directly with the first two interpretations.

You should select the Word Count checkbox if the count is to be interpreted as the number of 16-bit words to be transferred. You should leave the Word Count checkbox unselected if the count is to be interpreted as the number of values to be transferred.

Grouping: Single Values. Normally, Modsak will try to transfer as many values as possible in each read or write request that it sends to the slave. If you select the Single Values checkbox, then it will transfer only one value in each request.

Error Handling: Continue Polling. Normally, Modsak will stop polling if it receives an error response from the slave. If you select the Continue Polling, then it will continue polling if it receives an error response.

Pass Delay. The Pass Delay field is used to insert a time delay into the polling sequence to reduce the load on the slave (and maybe also on the computer running Modsak). The delay is inserted after each complete pass through all the registers. The delay is measured in milliseconds. (Also see Request Delay).