read

R2026b

Read data from Modbus server

collapse all in page

Syntax

moddata = read(modbusClientObj,target,address)
moddata = read(modbusClientObj,target,address,count)
moddata = read(modbusClientObj,target,address,count,serverId)
moddata = read(modbusClientObj,target,address,count,precision)
moddata = read(modbusClientObj,target,address,count,serverId,precision)

Description

moddata = read(modbusClientObj,target,address) reads data from the specified target register and address on the Modbus server connected to the client specified by modbusClientObj.

example

moddata = read(modbusClientObj,target,address,count) reads data from multiple registers beginning at the specified register address. The count argument specifies the number consecutive registers to read.

example

moddata = read(modbusClientObj,target,address,count,serverId) additionally specifies serverId to send the read command to a specific server.

example

moddata = read(modbusClientObj,target,address,count,precision) additionally specifies the precision to determine how the register data is interpreted.

example

moddata = read(modbusClientObj,target,address,count,serverId,precision) specifies both the server address and the register data format.

example

Examples

collapse all

To read the value of a coil in the remote server, set read target to "coils". A coil in the Modbus protocol is a single output bit. A value of 1 indicates the coil is on and a value of 0 means it is off.

Read one coil at address 1.

moddata = read(m,"coils",1)
moddata =

   1

To read the values from up to 2000 contiguous discrete inputs in the remote server starting at the specified address, set the read target to "inputs". A discrete input is a single input bit. A value of 1 indicates the input is on and a value of 0 means it is off.

Read 10 discrete inputs starting at address 2 from server ID 3.

moddata = read(m,"inputs",2,10,3)
moddata =

   1   1   0   1   1   0   1   0   0   1

To read the values from up to 125 contiguous discrete input registers in the remote server starting at the specified address, set the read target to "inputregs". An input register is a 16-bit read-only register.

Read 4 input registers starting at address 20 with uint32 precision. The precision argument specifies how the raw register data is interpreted. A precision of uint32 means each value is read as an unsigned 32-bit integer spanning two consecutive registers, so a count of 4 reads 4 values from 8 registers. The precision does not affect the returned data type, which is always double.

moddata = read(m,"inputregs",20,4,"uint32")
moddata =

   1812345   2098765   1567890   2045678

To read the values from up to 125 contiguous discrete holding registers in the remote server starting at the specified address, set the read target to "holdingregs". A holding register is a 16-bit read/write register.

Read 5 holding registers starting at address 2.

moddata = read(m,"holdingregs",2,5)
moddata = 

   27640   60013   51918   62881   34836

You can read any of the four target types and also specify optional serverId and precision arguments.

Read 8 holding registers starting at address 1 using a precision of uint32 from Server ID 3.

moddata = read(m,"holdingregs",1,8,3,"uint32");

For holdingregs and inputregs targets, you can read contiguous values of different data types (precisions) by specifying the data type for each value.

To read the 10 values as mixed data types, specify both count and precision as arrays of values. The function reads the number of counts specified in each element of the count array using the precision specified in the corresponding element of the precision array. For example:

count = [3 2 3 2];
precision = ["uint16","single","double","int16"];
moddata = read(m,"holdingregs",500,count,precision);

In this case, the function reads 3 values of data type uint16, 2 values of data type single, 3 values of data type double, and 2 values of data type int16. The registers are contiguous, starting at address 500.

Input Arguments

collapse all

Modbus client, specified either as an icomm.interface.modbus.tcpip.Modbus or icomm.interface.modbus.serialrtu.Modbus object, based on the transport layer used for communication. Create the client using the modbus function.

Target area to read, specified as a character vector or string. Valid values are:

  • "coils" — Single-bit read/write values. A value of 1 indicates on and 0 indicates off.

  • "inputs" — Single-bit read-only values. A value of 1 indicates on and 0 indicates off.

  • "inputregs" — 16-bit read-only registers.

  • "holdingregs" — 16-bit read/write registers.

Example: read(m,"coils",1,8) reads 8 coils starting at address 1.

Data Types: string | char

Starting address for read operation, specified as a positive scalar. Use 1-based addressing because the function subtracts 1 from the specified address.

Example: read(m,"coils",2,10) reads 10 coils starting at address 2.

Data Types: double

Number of values to read, specified as a positive scalar or a vector of positive values. If you do not specify a count, the function reads one value. The maximum number of values depends on the specified precision because each value can occupy one or more contiguous Modbus registers.

While reading mixed data types, specify count as a vector of positive integers with a corresponding array of precisions. For more information, see Read Mixed Data Types.

Example: read(m,"coils",2,12) reads 12 coils starting at address 2.

Data Types: double

Server identifier for read operation, specified as a nonnegative scalar. The server identifier corresponds to the unit identifier in Modbus TCP and the server address in Modbus Serial RTU. If you do not specify a serverId, the function uses the default value of 1. Valid values are 0-255, with 0 being the broadcast address.

Example: read(m,"coils",1,8,3); reads 8 coils starting at address 1 from server ID 3.

Data Types: double

Data format of the register being read from on the Modbus server, specified as a character vector or string. Valid values are "uint16", "int16", "uint32", "int32", "uint64", "int64", "single", and "double". This argument is optional; the default is uint16.

precision does not refer to the return type, which is always double. It specifies how to interpret the register data.

To read mixed data types, specify precision as a cell array of character vectors or strings, or a string array, with a corresponding array of counts. For more information, see Read Mixed Data Types.

Example: read(m,"holdingregs",2,6,"uint32") reads 6 values from holding registers starting at address 2, interpreting each pair of consecutive registers as a uint32 value.

Data Types: char | string

Output Arguments

collapse all

Read data values, returned as a double or array of double values.

Data Types: double

Extended Capabilities

expand all

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2017a

expand all

See Also

| | |

Topics