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