Main Content

read

Read data from a Modbus server

collapse all in page

Syntax

read(m,target,address)
read(m,target,address,count)
read(m,target,address,count,serverId,precision)

Description

read(m,target,address) reads one data value to Modbus object m from target type target at the starting address address. The function reads one value by default. If you want to read more than one value, add the count argument.

example

read(m,target,address,count) reads data to Modbus object m from target type targetat the starting address address using the number of values to read count.

example

read(m,target,address,count,serverId,precision) additionally specifies serverId, which is the address of the server to send the read command to, and the precision, which is the data format of the register being read.

Examples

collapse all

If the read target is coils, the function reads the values from 1–2000 contiguous coils in the remote server, starting 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 8 coils, starting at address 1. The address parameter is the starting address of the coils to read, and the count parameter is the number of coils to read.

read(m,'coils',1,8)
ans = 

   1   1   0   1   1   0   1   0

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. The address parameter is the starting address of the inputs to read, and the count parameter is the number of inputs to read.

read(m,'inputs',2,10)
ans = 

   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. The address parameter is the starting address of the input registers to read, and the count parameter is the number of input registers to read.

read(m,'inputregs',20,4)
ans = 

   27640   60013   51918   62881

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. The address parameter is the starting address of the holding registers to read, and the count parameter is the number of holding registers to read.

read(m,'holdingregs',2,5)
ans = 

   27640   60013   51918   62881   34836

You can read any of the four types of targets and also specify the optional parameters for server ID, and you can specify precision for the two types of registers. You can set either option by itself or set both the serverId option and the precision option together. Both options should be listed after the required arguments.

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

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 within the syntax of the read function, or set up variables containing arrays of counts and precisions. Both methods are shown here.

Read contiguous registers of the same data type.

read(m,'holdingregs',500,10,'uint32');

In that example, the target type is holding registers, the starting address is 500, the count is 10, and the precision is uint32.

If you wanted to have the 10 values be of mixed data types, you can use this syntax:

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

You use an array of values within the command for both count and precision. In this case, the counts are 3, 2, 3, and 2. The command will read 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'}
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

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'. Target must be the first argument after the object name. This example reads 8 coils starting at address 1.

Example: read(m,'coils',1,8)

Data Types: char

Starting address to read from, specified as a double. Address must be the second argument after the object name. This example reads 10 coils starting at address 2.

Example: read(m,'coils',2,10)

Data Types: double

Number of values to read, specified as a double. Count must be the third argument after the object name. If you do not specify a count, the default of 1 is used. This example reads 12 coils starting at address 2.

Example: read(m,'coils',2,12)

Data Types: double

Address of the server to send the read command to, specified as a double. Server ID must be specified after the object name, target, address, and count. If you do not specify a serverId, the default of 1 is used. Valid values are 0-247, with 0 being the broadcast address.

Note

What some devices refer to as a slaveID property, may work as a serverID property in the Modbus interface. For some manufacturers a slave ID is sometimes referred to as a server ID. If your device uses a slaveID property, it might work to use it as the serverID property with the read command as described here.

This example reads 8 coils starting at address 1 from server ID 3.

Example: read(m,'coils',1,8,3);

Data Types: double

Data format of the register being read from on the Modbus server, specified as a character vector or string. Precision must be specified after the object name, target, address, and count. Valid values are 'uint16', 'int16', 'uint32', 'int32', 'uint64', 'int64', 'single', and 'double'. This argument is optional, and 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.

This example reads 6 holding registers starting at address 2 using a precision of 'uint32'.

Example: read(m,'holdingregs',2,6,'uint32');

Data Types: char

Extended Capabilities

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

Version History

Introduced in R2017a

See Also

| | |

Topics