modbus-read

Description

The modbus-read block is used to read data from a Modbus RTU device over the RS485 port. It can perform reads cyclically, after an event on the main input, or in both modes at the same time.

The block has one main input and two outputs. It does not require the use of inputs labeled with the tag block.

The supported read method depends on the functionCode parameter:

• 1: read coils
• 2: read discrete inputs
• 3: read holding registers
• 4: read input registers

Configuration parameters

Parameter name	Value
Trigger edge (input_edge)	Required parameter that defines which event on the main input starts a read. Supported values: rising, falling, both, true, false, null, none.
Modbus function code (functionCode)	Required parameter. Defines the read type: 1 for coils, 2 for discrete inputs, 3 for holding registers, 4 for input registers.
Device address (deviceAddress)	Required parameter. Modbus slave device address in the range 1 to 255.
Starting address (registerAddress)	Required parameter. Address of the first coil, input, or register in the range 0 to 65535.
Bit count (bitCount)	Required for functions 1 and 2. Defines the number of bits to read. Allowed range: 1-32.
Register value type (valueType)	Required for functions 3 and 4. Allowed values: SIGNED_NUMBER16, SIGNED_NUMBER32, UNSIGNED_NUMBER16, UNSIGNED_NUMBER32, and FLOAT.
Divisor (divisor)	Required parameter. After processing, the read value is divided by this parameter. Allowed range: 1-4294967295. The block does not round the result after division.
Precision (precision)	Required parameter in the range 0-3. Defines the target precision of the value after applying divisor. The block truncates less significant digits instead of rounding the result.
Byte order (endianess)	Required when the read covers more than 1 byte of data, that is for functions 3 and 4, and for functions 1 and 2 when bitCount > 8. Allowed values: LittleEndian, BigEndian, SwapBytes, SwapWords.
Refresh interval (refreshInterval)	Required parameter. Defines the time between consecutive cyclic reads in milliseconds. Allowed range: 0-3600000 ms. The value 0 disables cyclic reading.
Response timeout (responseTimeout)	Required parameter. Maximum time to wait for the device response in milliseconds. Allowed range: 10-60000 ms.
RS485 configuration (server)	Required parameter. Identifier of the modbus-client block from which the RS485 port settings are taken.

Input handling

The block has one main input. The value appearing at this input is not interpreted as the data to read from Modbus. It is used only to trigger the read operation according to the input_edge parameter.

The input_edge parameter works as follows:

• rising: read after a change interpreted as false -> true
• falling: read after a change interpreted as true -> false
• both: read on every logical state change
• true: read after every input value interpreted as true
• false: read after every input value interpreted as false
• null: read only after receiving the null value
• none: disable read triggering by normal input events

Additional operating rules:

• For rising, falling, both, true, and false, the input must be convertible to a logical value. Other values are ignored.
• If refreshInterval > 0, the block also performs cyclic reads. The first read attempt happens about 2 seconds after project initialization is finished.
• Each next cyclic read is scheduled only after the previous operation has finished.
• If the block is already waiting for a response from the Modbus device, further input triggers and further read attempts are ignored until the current operation finishes.

Interpretation of the read value

How the response is interpreted depends on the selected functionCode.

For functions 1 and 2:

• the block reads from 1 to 32 bits
• the received bits are interpreted as one non-negative numeric value
• the endianess parameter matters only when bitCount > 8

For functions 3 and 4:

• SIGNED_NUMBER16: read one register as a signed 16-bit number
• SIGNED_NUMBER32: read two registers as a signed 32-bit number
• UNSIGNED_NUMBER16: read one register as an unsigned 16-bit number
• UNSIGNED_NUMBER32: read two registers as an unsigned 32-bit number
• FLOAT: read two registers as a 32-bit floating-point number

After reading and interpreting the data, the block:

• divides the value by divisor, if divisor > 1
• truncates the fractional part according to precision
• sends the result to the output as a numeric value

Block outputs

Output number and name	Output description
1. Read value.	Returns the last correctly read and processed numeric value from the Modbus device. The output is updated only after a successful read and correct response interpretation.
2. Data connection status.	Returns true when the last read finished successfully and the block has a current value available. Returns false when a communication error, response error, or data processing error occurs. In case of an error, the first output keeps the last correctly read value.

Block status description

The description visible below the block shows the result of the last completed operation:

• after a successful read, it is the textual representation of the read value
• after an error, it is the error message

Errors visible to the user

The block can display the following error messages:

Error code	Error description
Invalid input edge configuration.	The input_edge parameter is invalid or has not been configured.
Invalid function code configuration.	The functionCode parameter has an invalid value.
Invalid device address configuration.	The deviceAddress parameter is invalid or outside the 1-255 range.
Invalid register address configuration.	The registerAddress parameter is invalid or outside the 0-65535 range.
Invalid bit count configuration.	The bitCount parameter is invalid, out of range, or required for function 1 or 2 but not configured correctly.
Invalid value type configuration.	The valueType parameter is invalid or required for function 3 or 4 but not configured correctly.
Invalid divisor configuration.	The divisor parameter is invalid or outside the allowed range.
Invalid precision configuration.	The precision parameter is invalid or outside the 0-3 range.
Invalid endianess configuration.	The endianess parameter is required for the selected read mode but has not been configured correctly.
Invalid refresh interval configuration.	The refreshInterval parameter is invalid or outside the 0-3600000 ms range.
Invalid response timeout configuration.	The responseTimeout parameter is invalid or outside the 10-60000 ms range.
Missing RS485 configuration.	No valid modbus-client block was selected in the server parameter.
Baudrate configuration mismatch.	Different Modbus blocks in the project use inconsistent RS485 baudrate settings.
Parity configuration mismatch.	Different Modbus blocks in the project use inconsistent RS485 parity settings.
Stop bits configuration mismatch.	Different Modbus blocks in the project use inconsistent RS485 stop bit settings.
Invalid baudrate configuration.	The RS485 settings provided by the modbus-client block are invalid.
Invalid parity configuration.	The RS485 settings provided by the modbus-client block are invalid.
Invalid stop bits configuration.	The RS485 settings provided by the modbus-client block are invalid.
Invalid parity or stop bits configuration.	The configured combination of parity and stop bits is not allowed.
RS485 setup incomplete.	The RS485 configuration has not yet been prepared correctly in the runtime.
RS485 port missing.	No RS485 port is available in the runtime to execute the operation.
Function code not supported	The Modbus device rejected the request because it does not support the selected function.
Invalid address	The Modbus device reported an invalid coil, input, or register address.
Invalid quantity	The Modbus device reported an invalid number of items to read.
IO error	An input/output error occurred during communication.
Unknown modbus exception code	The Modbus device returned an unknown exception code.
Master/RS485 timeout	The operation timed out on the master side or on the RS485 bus.
Slave timeout	The slave device did not respond within the expected time.
Invalid request	The request sent to the device was considered invalid.
Internal error	An internal error occurred while preparing or executing the operation.
RS485 busy	The RS485 bus is currently busy.
RS485 RX overrun	An RS485 receive overrun occurred.
RS485 frame error	An RS485 frame error occurred during transmission.
Value parse failed	The device response was received, but the value could not be read from it correctly.
Unknown register value type	A register value type inconsistency occurred while processing the response.
Invalid register value type	An invalid register value type occurred while processing the response.
Invalid precision	An invalid precision value was detected while processing the response.

Examples

• If functionCode = 1, bitCount = 4, and the device returns bits corresponding to the value 13, output 1 will contain the number 13, and output 2 will contain true.
• If functionCode = 3, valueType = SIGNED_NUMBER16, divisor = 10, and the device returns a register with the value 215, the block will return 21.5.
• If functionCode = 4, valueType = FLOAT, divisor = 1, precision = 2, and the device returns the value 23.987, the result will be truncated to the precision defined by the configuration and sent to output 1.
• If the read ends with a communication error, output 2 will contain false, and the block description will be replaced with the error message.