Main Content

Read Data from a Modbus Server

Types of Data You Can Read Over Modbus

The read function performs read operations from four types of target-addressable areas:

  • Coils

  • Inputs

  • Input registers

  • Holding registers

When you perform the read, you must specify the target type (target), the starting address (address), and the number of values to read (count). You can also optionally specify the address of the server (serverId) for any target type, and the data format (precision) for registers.

For an example showing the entire workflow of reading a holding register on a PLC, see Read Temperature from a Remote Temperature Sensor.

Read Coils Over Modbus

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.

The syntax to read coils is:

read(obj,'coils',address,count)

The obj parameter is the name of the Modbus object. The following examples assume you have created a Modbus object, m. For information on creating the object, see Create a Modbus Connection.

The address parameter is the starting address of the coils to read, specified as a double. The count parameter is the number of coils to read, specified as a double. If the read is successful, it returns a vector of double values of 1 or 0, where the first value in the vector corresponds to the coil value at the starting address.

This example reads 8 coils, starting at address 1.

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

   1   1   0   1   1   0   1   0

You can also read values into a variable for later access.

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

   1   1   0   1   1   0   1   0

Read Inputs over Modbus

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.

The syntax to read inputs is:

read(obj,'inputs',address,count)

The obj parameter is the name of the Modbus object. The following examples assume you have created a Modbus object, m. For information on creating the object, see Create a Modbus Connection.

The address parameter is the starting address of the inputs to read, specified as a double. The count parameter is the number of inputs to read, specified as a double. If the read operation is successful, it returns a vector of double values of 1 or 0, where the first value in the vector corresponds to the input value at the starting address.

This example reads 10 discrete inputs, starting at address 2.

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

   1   1   0   1   1   0   1   0   0   1

Read Input Registers over Modbus

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.

The syntax to read input registers is:

read(obj,'inputregs',address,count)

The obj parameter is the name of the Modbus object. The following examples assume you have created a Modbus object, m. For information on creating the object, see Create a Modbus Connection.

The address parameter is the starting address of the input registers to read, specified as a double. The count parameter is the number of input registers to read, specified as a double. If the read operation is successful, it returns a vector of doubles. Each double represents a 16-bit register value, where the first value in the vector corresponds to the input register value at the starting address.

This example reads 4 input registers, starting at address 20.

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

   27640   60013   51918   62881

Read Holding Registers over Modbus

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.

The syntax to read inputs is:

read(obj,'holdingregs',address,count)

The obj parameter is the name of the Modbus object. The following examples assume you have created a Modbus object, m. For information on creating the object, see Create a Modbus Connection.

The address parameter is the starting address of the holding registers to read,specified as a double. The count parameter is the number of holding registers to read, specified as a double. If the read operation is successful, it returns a vector of doubles. Each double represents a 16-bit register value, where the first value in the vector corresponds to the holding register value at the starting address.

This example reads 4 holding registers, starting at address 20.

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

   27640   60013   51918   62881

For an example showing the entire workflow of reading a holding register on a PLC, see Read Temperature from a Remote Temperature Sensor.

Specify Server ID and Precision

You can read any of the four types of targets and also specify the optional parameters for server ID, and can specify precision for registers.

Server ID Option

The serverId argument specifies the address of the server to send the read command to. Valid values are 0–247, with 0 being the broadcast address. This argument is optional, and the default is 1.

Note

What some devices refer to as a slaveID property, might 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.

The syntax to specify server ID is:

read(obj,target,address,count,serverId)

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

read(m,'coils',1,8,3)

Precision Option

The 'precision' argument specifies the data format of the register being read on the Modbus server. 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 only specifies how to interpret the register data.

The syntax to specify precision is:

read(obj,target,address,count,precision)

This example reads 8 holding registers starting at address 1 using a precision of 'uint32'.

read(m,'holdingregs',1,8,'uint32')

Both Options

You can set both the serverId option and the 'precision' option together when the target is a register. When you use both options, the serverId is listed first after the required arguments.

The syntax to specify both Server ID and precision is:

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

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

read(m,'holdingregs',1,8,3,'uint32')

Read Mixed Data Types

You can read contiguous values of different data types (precisions) in a single read operation 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.

Within the read Syntax

An example of the read function with one data type is:

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. To read 10 values of mixed data types, you can use this syntax:

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

You use arrays to specify both counts and precisions. In this case, the counts are 3, 2, 3, and 2. 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. This example reads 3 uint16 values from addresses 500-502, 2 single values from addresses 503-506, 3 double values from addresses 507-518, and 2 int16 values from addresses 519-520, all in one operation.

Use Variables

Instead of using literal arrays inside the read function as shown above, you can specify variables with array values as function arguments. The equivalent for the example shown above 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.