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.

Reading 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 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, and it is a double. The count parameter is the number of coils to read, and it is a double. If the read is successful, it returns a vector of doubles, each with the value 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 create a variable to be read later.

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

data = 

   1   1   0   1   1   0   1   0

Reading 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 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, and it is a double. The count parameter is the number of inputs to read, and it is a double. If the read operation is successful, it returns a vector of doubles, each with the 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

Reading 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 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, and it is a double. The count parameter is the number of input registers to read, and it is 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

Reading 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 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, and it is a double. The count parameter is the number of holding registers to read, and it is 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.

Specifying 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, 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.

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 from 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 should be 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');

Reading 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 below.

Within the read Syntax

The syntax of the read function is as follows:

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. In this example it reads 3 uint16 values from address 500-502, 2 single values from address 503-506, 3 double values from address 507-518, and 2 int16 values from address 519-520, all in one read operation.

Using Variables

Instead of using arrays inside the read command as shown above, you can also use arrays as variables in the command. 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.