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. count 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

If the read target is coils, the function reads the value of a coil in the remote server at the specified address. A coil 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

If the read target is inputs, the function reads the values from 1–2000 contiguous discrete inputs in the remote server, starting at the specified address. 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

If the read target is input registers, the function reads the values from 1–125 contiguous input registers in the remote server, starting at the specified address. An input register is a 16-bit read-only register.

Read 4 input registers starting at address 20 with uint32 precision.

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

   1812345   2098765   1567890   2045678

If the read target is holding registers, the function reads the values from 1–125 contiguous holding registers in the remote server, starting at the specified address. 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 parameters. List both parameters after the required 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");

You can read contiguous values of different data types (precisions) by specifying the data type for each value. You can do that in the syntax of the read function, or set up variables containing arrays of counts and precisions. Both methods are shown here. This syntax is supported for holdingregs and inputregs targets.

Read 10 holding registers starting at address 500 with uint32 precision.

moddata = read(m,"holdingregs",500,10,"uint32");

To read the 10 values as mixed data types, use this syntax:

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

Specify both count and precision as arrays of values. In this case, the counts are 3, 2, 3, and 2. The command 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.

Instead of using arrays inside the read command as shown in the previous step, you can also use arrays as variables in the command. The equivalent code for the same example is:

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

Using variables is convenient when you have a lot of values to read and they are of mixed data types.

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. You can create the client using the modbus function.

Target area to read, specified as a character vector or string. You can perform a Modbus read operation on four types of targets: coils, inputs, input registers, and holding registers, corresponding to the values "coils", "inputs", "inputregs", and "holdingregs".

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

Data Types: char

Starting address to read from, 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. If you do not specify a count, the function uses the default of 1. The maximum number of values depends on the specified precision because each value can occupy one or more contiguous Modbus registers.

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

Data Types: double

Address of the server to send the read command to, specified as a nonnegative scalar. If you do not specify a serverId, the function uses the default as 1. Valid values are 0-255, with 0 being the broadcast address.

Note

The serverId refers to the unit identifier for Modbus TCP.

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'.

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

Example: read(m,"holdingregs",2,6,"uint32"); reads 6 holding registers starting at address 2 using a precision of 'uint32'.

Data Types: char

Output Arguments

collapse all

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

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