ModbusX class

ModbusX

Modbus RTU/ASCii/TCP Client (Master)

Since R2019b

Description

A ModbusX object represents a Modbus Master in the same Modbus network. After creating the object, use dot notation to  call methods.

With the help of  hardware "Modbus dual Masters Adaptor adaptor" from Dafulai Electronics, you can access Modbus RTU/ASCii Servers or Modbus TCP Servers.

Compared with Matlab built-in modbus object, our ModbusX supports user defined Function Code. And every method has Error Code return, so you can know modbus exception code.

Almost all methods are compatible with Matlab built-in modbus object. Furthermore, we provide Simulink blocks library for ModbusX

We supports Modbus ASCii, please use ConfigTool.exe PC software to configure physical bus feature before using ModbusX.

Creation

Syntax

m = ModbusX(Transport,DeviceAddress)

m = ModbusX(Transport,DeviceAddress,Port)

m = ModbusX(Transport,DeviceAddress,Name,Value)

m = ModbusX(Transport,Port)

m = ModbusX(Transport,Port,Name,Value)

Description

example

m = ModbusX(Transport,DeviceAddress) constructs a Modbus object, m, over the transport type Transport using the specified DeviceAddress.When the transport is 'tcpip', DeviceAddress must be specified as the second argument. DeviceAddress is the IP address or host name of the Modbus server..

m = ModbusX(Transport,DeviceAddress,Port) additionally specifies Port. When the transport is 'tcpip', DeviceAddress must be specified. Port is the remote port used by the Modbus server. Port is optional, and it defaults to 502, which is the reserved port for Modbus.

m = ModbusX(Transport,DeviceAddress,Name,Value) specifies additional options with one or more name-value pair arguments using any of the previous syntaxes. For example, you can specify a timeout value. The Timeout property specifies the waiting time to complete read and write operations in seconds, and the default is 1.1.

m = ModbusX(Transport,Port) constructs a Modbus object m over the transport type Transport using the specified Port. When the transport is 'serialrtu', Port must be specified. This argument is the serial port that the Modbus dual Masters Adaptor hardware is connected to PC, such as 'COM3'.

m = ModbusX(Transport,Port,Name,Value) specifies additional options with one or more name-value pair arguments using any of the previous syntaxes. For example, you can specify NumRetries, the number of retries to perform if there is no reply from the server after a timeout.

Input Arguments

Transport  -- Physical transport layer for device communication.

character vector | string scalar

Physical transport layer for device communication, specified as a character vector or string. Specify transport type as the first argument when you create the modbus object. You must set the transport type as either 'tcpip' or 'serialrtu' to designate the protocol you want to use.

For example,m = ModbusX('tcpip','192.168.2.1')

DeviceAddress — IP address or host name of Modbus server

character vector | string scalar

IP address or host name of Modbus server, specified as a character vector or string.

If transport is TCP/IP, it is required as the second argument during object creation.

Example: m = ModbusX('tcpip','192.168.2.1')

Port — Remote port used by Modbus server

502 (default) | double scalar

Remote port used by Modbus server, specified as a double. Optional as a third argument during object creation if transport is TCP/IP. The default of 502 is used if none is specified. Example: m = ModbusX('tcpip','192.168.2.1',308)

Port — Serial port Modbus server is connected to PC by this Port.

character vector | string scalar

Serial port "Modbus dual Masters Adaptor hardware USB or Bluetooth" is connected to by this argument, e.g. 'COM1' in windows OS, or "/dev/ttyUSB0" under Linux OS, specified as a character vector or string. If transport is Serial RTU, it is required as the second argument during object creation. Example: m = ModbusX('serialrtu','COM3')

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Please, use commas to separate each name and value, and enclose Name in quotes.

For example, m = ModbusX('serialrtu','COM3','Timeout',20)

You can use Name-Value pairs to set the following arguments:

Value is scalar string or char array. It denote the words order when register data type is "uint32/int32/single/uint64/int64/double". Valid value is "big-endian" or "little-endian". Default="big-endian"

Value is scalar double. Maximum time in seconds to wait for a response from the Modbus server.

Maximum time in seconds to wait for a response from the Modbus server, specified as the comma-separated pair consisting of 'Timeout' and a positive value of type double. .  The default is 1.1. You can change the value either during object creation or after you create the object. Example:

m = ModbusX('serialrtu','COM3','Timeout',20)

Value is scalar double. Number of retries to perform if there is no reply or exception reply from the server after a timeout, specified as the comma-separated pair consisting of 'NumRetries' and a positive value of type double.You can change the value either during object creation. The default is 3

Value is scalar string or char array. Modbus dual Masters Adaptor hardware is connected to PC by this Port. (This Name-Value is only used for Modbus TCP). When Modbus Server is Modbus TCP, we used this COM to identify whether "Modbus dual Masters Adaptor hardware" connects PC. Our Modbus object only works when "Modbus dual Masters Adaptor hardware" connects PC. Specified as the comma-separated pair consisting of 'COM' and a value of type string or character vector. You can only change the value during object creation. Default='COM1'.

Value is scalar double.  Default is 19200 bits per second. Valid Value is 4800/9600/19200/28800/38400/43000/57600/115200.  Note: This baud rate is not actual Modbus baud rate. It is baud rate for Modbus dual Masters Adaptor Hardware interface with PC. Actual Modbus baud rate is decided by PC ConfigTool.exe software. Modbus TCP needs this Baud rate to identify Modbus dual Masters Adaptor Hardware.

Value is scalar string or char array. Valid choices are 'none' (default), 'even', 'odd'.

Value is scalar double.  Valid choices are 1 (default) and 2.

Examples

When the transport is TCP/IP, you must specify the IP address or host name of the Modbus server.  And your PC must connect our "Modbus dual Masters Adaptor hardware". So if  your hardware USB or Bluetooth Serial port is not COM1, you must set up "COM" of name-value pair. . The following statement is usually used in general project:

m=ModbusX('tcpip', '192.168.2.1', 'COM', 'COM8', 'BaudRate', 115200, 'Parity', 'none' );

When the transport is 'serialrtu', you must specify a Port argument. This is the serial port that the Modbus dual Masters Adaptor hardware is connected to PC. This baudRate is not actual Modbus baud rate. It is baud rate for Modbus dual Masters Adaptor Hardware interface with PC. Actual Modbus baud rate is decided by PC ConfigTool.exe software. And RTU or ASCii is decided by PC ConfigTool.exe software too.

Create the Modbus RTU/ASCii master object m specifying a Port of 'COM3'..

m = ModbusX('serialrtu','COM3', 'BaudRate',19200,'NumRetries',5 );

Properties

scalar string or char array. IP address or host name of Modbus server, specified as a character vector or string. If transport is TCP/IP, it is required as the second argument during object creation.

scalar double. Remote port used by Modbus server, specified as a double. Optional as a third argument during object creation if transport is TCP/IP. The default of 502 is used if none is specified.

scalar string or char array.  Serial port "Modbus dual Masters Adaptor hardware USB or Bluetooth" is connected to, e.g. 'COM1', specified as a character vector or string. If transport is Serial RTU, it is required as the second argument during object creation.

scalar double. The default is 1.1. Maximum time in seconds to wait for a response from the Modbus server. You can change the value either during object creation or after you create the object.

scalar double. The default is 3. Number of retries to perform if there is no reply or exception reply from the server after a timeout. You can change the value either during object creation or after you create the object.

scalar double. Default is 19200 bits per second. Valid Value is 4800/9600/19200/28800/38400/43000/57600/115200.  Note: This baud rate is not actual Modbus baud rate. It is baud rate for Modbus dual Masters Adaptor Hardware interface with PC. Actual Modbus baud rate is decided by PC ConfigTool.exe software. Modbus TCP needs this Baud rate to identify Modbus dual Masters Adaptor Hardware.  You can change the property only during object creation.

scalar string or char array.  Valid choices are 'none' (default), 'even', 'odd'. Note: This Parity is not actual Modbus RTU/ASCii Parity. It is parity for Modbus dual Masters Adaptor Hardware interface with PC. Actual Modbus Parity is decided by PC ConfigTool.exe software. Modbus TCP needs this parity to identify Modbus dual Masters Adaptor Hardware.  You can change the property only during object creation.

scalar double. Valid choices are 1 (default) and 2. Note: This StopBits is not actual Modbus RTU/ASCii StopBits. It is StopBits for Modbus dual Masters Adaptor Hardware interface with PC. Actual Modbus StopBits is decided by PC ConfigTool.exe software. Modbus TCP needs this StopBits to identify Modbus dual Masters Adaptor Hardware.  You can change the property only during object creation.

scalar string or char array. It denote the words order when register data type is "uint32/int32/single/uint64/int64/double". Valid value is "big-endian" or "little-endian". Default="big-endian". You can change it in the run-time by assignment

Object Functions (Or Methods)

Events

None

All methods details

read

Perform a read operation on the connected Modbus server.

Since R2019b

Syntax

[moddata,ErrCode] = read(obj,target,address)

[moddata,ErrCode] = read(obj,target,address,count)

[moddata,ErrCode] = read(obj,target,address,count,serverId)

[moddata,ErrCode] = read(obj,target,address,count,'precision')

[moddata,ErrCode] = read(obj,target,address,count,serverId,'precision')

Description

This function will perform a read operation from one of four target addressable areas: Coils, Inputs, Holding Registers, or Input Registers. Each of the four areas corresponds to a unique Modbus function code, which may or may not be supported by the connected Modbus server.

Input Arguments

'single' and 'double' conversions conform to the IEEE 754 floating point standard. For signed integers a two's complement conversion is performed. Note that 'precision' does not refer to the return type (always 'double'), it only specifies how to interpret the register data.

Precision is a string or char array when doing reads of the same data type. For reading multiple contiguous registers containing different data types, precision must be a cell array of strings or character vectors, or a string array of precisions. The number of precision values must match the number of count values.

Only for tagets: inputregs and holdingregs.

Output Arguments

Row vector for reading result in double number type. It will be [ ] if failed

scalar double. The reason of failure in reading,  0 denotes success, 1 denotes ILLEGAL FUNCTION, 2 denotes ILLEGAL DATA ADDRESS, 3 denotes ILLEGAL DATA VALUE , 4 denotes SLAVE DEVICE FAILURE, 6 denotes SLAVE DEVICE BUSY, 16 denotes timeout, 17 denotes frame format error, 18 denotes CRC error.

Examples

If you are running our "Modbus dual Masters Adaptor hardware" for the first time,  please run ConfigTool.exe in Windows OS.  Screenshot is shown below:

We must use USB serial port to do configure (You cannot use Bluetooth serial port to do configure because Bluetooth needs to be configured too).  In above figure, UART1 is one port actual Modbus RTU/ASCii Server is connected to. So UART1 settings are actual Modbus settings.  UART2 is USB Serial port which is connected to our PC.  So if you use USB serial port to access Modbus RTU/ASCii Server, please use these settings in MATLAB object construction function (ModbusX object).

UART3 is Bluetooth Serial port which is connected to our PC. So if you use Bluetooth serial port to access Modbus RTU/ASCii Server, please use these settings in MATLAB object construction function (ModbusX object).

Firstly, we set up a ModbusX object (Modbus RTU/ASCii Master) with COM5.  All other properties are used default values, it means that  Baud Rate=19200,  Parity='none', StopBits=1, Timeout=1.1, NumRetries=3, and WordOrder='big-endian'

m=ModbusX('serialrtu', 'COM5',);

% Read 3 coil values starting at address 5 from Slave node's Server ID =1

address = 5;

[moddata,Error] = read(m,'coils',address,3,1);

% Read 2 holding registers whose data format is unsigned 16 bits integer and 4 holding registers

% whose data format is double, in one read, at address 10 and Server ID=2.

address = 10;

precision = {'uint16', 'double'};

count = [2, 4];

[moddata, Error] = read(m, 'holdingregs', address, count,2, precision);

readUserDefinedInputRegs

Perform a input regs read operation by specified FC on the connected Modbus server.

Since R2019b

Syntax

[moddata,ErrCode] = readUserDefinedInputRegs(obj,FC,address)

[moddata,ErrCode] = readUserDefinedInputRegs(obj,FC,address,count)

[moddata,ErrCode] = readUserDefinedInputRegs(obj,FC,address,count,serverId)

[moddata,ErrCode] = readUserDefinedInputRegs(obj,FC,address,count,'precision')

[moddata,ErrCode] = readUserDefinedInputRegs(obj,FC,address,count,serverId,'precision')

Description

As we know, Standard read input registers function code is 4. However, Some server supports non-standard function code (not 4) for reading input registers. This function is designed for this purpose. This function will perform a input registers read operation by user defined Modbus function code, which may or may not be supported by the connected Modbus server.

Input Arguments

'single' and 'double' conversions conform to the IEEE 754 floating point standard. For signed integers a two's complement conversion is performed. Note that 'precision' does not refer to the return type (always 'double'), it only specifies how to interpret the register data.

Precision is a string or char array when doing reads of the same data type. For reading multiple contiguous registers containing different data types, precision must be a cell array of strings or character vectors, or a string array of precisions. The number of precision values must match the number of count values.

Output Arguments

Row vector for reading result in double number type. It will be [ ] if failed

scalar double. The reason of failure in reading,  0 denotes success, 1 denotes ILLEGAL FUNCTION, 2 denotes ILLEGAL DATA ADDRESS, 3 denotes ILLEGAL DATA VALUE , 4 denotes SLAVE DEVICE FAILURE, 6 denotes SLAVE DEVICE BUSY, 16 denotes timeout, 17 denotes frame format error, 18 denotes CRC error.

Examples

Firstly, we set up a ModbusX object (Modbus RTU/ASCii Master) with COM5.  All other properties are used default values, it means that  Baud Rate=19200,  Parity='none', StopBits=1, Timeout=1.1, NumRetries=3, and WordOrder='big-endian'

m=ModbusX('serialrtu', 'COM5',);

% Read 2 input registers whose data format is unsigned 16 bits integer and 4 holding registers

% whose data format is double, in one read, at address 10 and Server ID=3 But FC =14 which is not standard 4.

address = 10;

precision = {'uint16', 'double'};

count = [2, 4];

[moddata, Error] = readUserDefinedInputRegs(m, 14, address, count,3, precision);

readUserDefinedInputs

Perform a discrete regs read operation by specified FC on the connected Modbus server.

Since R2019b

Syntax

[moddata,ErrCode] = readUserDefinedInputs(obj,FC,address)

[moddata,ErrCode] = readUserDefinedInputs(obj,FC,address,count)

[moddata,ErrCode] = readUserDefinedInputs(obj,FC,address,count,serverId)

Description

As we know, Standard read discrete registers function code is 2. However, Some server supports non-standard function code (not 2) for reading discrete registers. This function is designed for this purpose. This function will perform a discrete registers read operation by user defined Modbus function code, which may or may not be supported by the connected Modbus server.

Input Arguments

Output Arguments

Row vector for reading result in logical number type. It will be [ ] if failed

scalar double. The reason of failure in reading,  0 denotes success, 1 denotes ILLEGAL FUNCTION, 2 denotes ILLEGAL DATA ADDRESS, 3 denotes ILLEGAL DATA VALUE , 4 denotes SLAVE DEVICE FAILURE, 6 denotes SLAVE DEVICE BUSY, 16 denotes timeout, 17 denotes frame format error, 18 denotes CRC error.

Examples

Firstly, we set up a ModbusX object (Modbus TCP Master) with remote TCP address='192.168.1.32'.  And Serial Port our hardware is connected to is 'COM5'.  All other properties are used default values, it means that  Port=502, Baud Rate=19200,  Parity='none', StopBits=1, Timeout=1.1, NumRetries=3, and WordOrder='big-endian'

m=ModbusX('tcpip', '192.168.1.32, 'COM', 'COM5');

% Read 3 coil values starting at address 5 from Slave node's Server ID =1 (default) , but FC=17

address = 5;

[moddata,Error] = readUserDefinedInputs(m, 17, address,3);

write

Perform a write operation to the connected Modbus server.

Since R2019b

Syntax

ErrCode = write(obj,target,address,values)

ErrCode = write(obj,target,address,values,serverId)

ErrCode = write(obj,target,address,values,ForceSingleWrite)

ErrCode = write(obj,target,address,values,'precision')

ErrCode = write(obj,target,address,values,serverId,'precision')

ErrCode = write(obj,target,address,values,serverId,ForceSingleWrite)

ErrCode = write(obj,target,address,values,serverId,'precision',ForceSingleWrite)

Description

This function will perform a write operation to one of two writable target addressable areas: Coils or Holding Registers. Each of the two areas can accept a write request to a single address, or a contiguous address range. Each possibility (single coil, multiple coils, single register, multiple registers) corresponds to a unique Modbus function code which may or may not be supported by the connected Modbus server.

Input Arguments

The values passed in to be written will be converted to register values based on the specified precision. 'single' and 'double' conversions conform to the IEEE 754 floating point standard. For signed integers a 2's complement conversion is performed.

Output Arguments

scalar double. The reason of failure in writing,  0 denotes success, 1 denotes ILLEGAL FUNCTION, 2 denotes ILLEGAL DATA ADDRESS, 3 denotes ILLEGAL DATA VALUE , 4 denotes SLAVE DEVICE FAILURE, 6 denotes SLAVE DEVICE BUSY, 16 denotes timeout, 17 denotes frame format error, 18 denotes CRC error.

Examples

Firstly, we set up a ModbusX object (Modbus TCP Master) with remote TCP address='192.168.1.32'.  And Serial Port our hardware is connected to is 'COM5'.  All other properties are used default values, it means that  Port=502, Baud Rate=19200,  Parity='none', StopBits=1, Timeout=1.1, NumRetries=3, and WordOrder='big-endian'

m=ModbusX('tcpip', '192.168.1.32, 'COM', 'COM5');

% set the server ID=1, the holding registers at address 22 to the value 2000 in multiple writings (FC=16)

ErrorCode= write(m,'holdingregs',22,2000,1);

% set the server ID=1, the holding registers at address 23 to the value 2000 in single writing (FC=6)

ErrorCode= write(m,'holdingregs',23,2000,1, true);

writeUserDefinedHoldingRegs

Perform a holding registers write operation by specified FC to the connected Modbus server.

Since R2019b

Syntax

ErrCode = writeUserDefinedHoldingRegs(obj,FC,address,values)

ErrCode = writeUserDefinedHoldingRegs(obj,FC,address,values,serverId)

ErrCode = writeUserDefinedHoldingRegs(obj,FC,address,values,'precision')

ErrCode = writeUserDefinedHoldingRegs(obj,FC,address,values,serverId,'precision')

Description

As we know, Standard write holding registers function code is 16 or 6. However, Some server supports non-standard function code (not 16 , not 6) for writing holding registers. This function is designed for this purpose. This function will perform a holding registers write operation by user defined Modbus function code, which may or may not be supported by the connected Modbus server.

Input Arguments

The values passed in to be written will be converted to register values based on the specified precision. 'single' and 'double' conversions conform to the IEEE 754 floating point standard. For signed integers a 2's complement conversion is performed.

Output Arguments

scalar double. The reason of failure in writing,  0 denotes success, 1 denotes ILLEGAL FUNCTION, 2 denotes ILLEGAL DATA ADDRESS, 3 denotes ILLEGAL DATA VALUE , 4 denotes SLAVE DEVICE FAILURE, 6 denotes SLAVE DEVICE BUSY, 16 denotes timeout, 17 denotes frame format error, 18 denotes CRC error.

Examples

Firstly, we set up a ModbusX object (Modbus TCP Master) with remote TCP address='192.168.1.32'.  And Serial Port our hardware is connected to is 'COM5'.  All other properties are used default values, it means that  Port=502, Baud Rate=19200,  Parity='none', StopBits=1, Timeout=1.1, NumRetries=3, and WordOrder='big-endian'

m=ModbusX('tcpip', '192.168.1.32, 'COM', 'COM5');

% set the server ID=2, the holding registers at address 22 to the value 2000 in FC=14

ErrorCode= writeUserDefinedHoldingRegs(m,14,22,2000,2);

writeUserDefinedCoils

Perform a coil registers write operation by specified FC to the connected Modbus server.

Since R2019b

Syntax

ErrCode = writeUserDefinedCoils(obj,FC,address,values)

ErrCode = writeUserDefinedCoils(obj,FC,address,values,serverId)

Description

As we know, Standard write coil registers function code is 15 or 5. However, Some server supports non-standard function code (not 15 , not 5) for writing coil registers. This function is designed for this purpose. This function will perform a coil registers write operation by user defined Modbus function code, which may or may not be supported by the connected Modbus server.

Input Arguments

Output Arguments

scalar double. The reason of failure in writing,  0 denotes success, 1 denotes ILLEGAL FUNCTION, 2 denotes ILLEGAL DATA ADDRESS, 3 denotes ILLEGAL DATA VALUE , 4 denotes SLAVE DEVICE FAILURE, 6 denotes SLAVE DEVICE BUSY, 16 denotes timeout, 17 denotes frame format error, 18 denotes CRC error.

Examples

Firstly, we set up a ModbusX object (Modbus RTU/ASCii Master) with COM5.  All other properties are used default values, it means that  Baud Rate=19200,  Parity='none', StopBits=1, Timeout=1.1, NumRetries=3, and WordOrder='big-endian'

m=ModbusX('serialrtu', 'COM5',);

% set the server ID=8, the coil registers at address 22 to the value true, address 23 to false in FC=13

ErrorCode= writeUserDefinedCoils(m,13,22,[true false ],8);

writeRead

Perform a write then read operation on the connected Modbus server in a single Modbus transaction.

Since R2019b

Syntax

[moddata,ErrCode] = writeRead(obj,writeAddress,writeData,readAddress,readCount)

[moddata,ErrCode] = writeRead(obj,writeAddress,writeData,readAddress,...

readCount,serverId)

[moddata,ErrCode] = writeRead(obj,writeAddress,writeData,'writePrecision',...

readAddress,readCount,'readPrecision')

[moddata,ErrCode] = writeRead(obj,writeAddress,writeData,'writePrecision',...

readAddress,readCount,'readPrecision',serverId)

Description

This function is used to perform a combination of one write operation and one read operation on groups of holding registers in a single Modbus transaction. The write operation is always performed before the read. The range of addresses to read must be contiguous, and the range of addresses to write must be contiguous, but each are specified independently and may or may not overlap.

Input Arguments

'single' and 'double' conversions conform to the IEEE 754 floating point standard. For signed integers a two's complement conversion is performed. Note that 'precision' does not refer to the return type (always 'double'), it only specifies how to interpret the register data.

Output Arguments

Row vector for reading result in double number type. It will be [ ] if failed

scalar double. The reason of failure in writing/reading,  0 denotes success, 1 denotes ILLEGAL FUNCTION, 2 denotes ILLEGAL DATA ADDRESS, 3 denotes ILLEGAL DATA VALUE , 4 denotes SLAVE DEVICE FAILURE, 6 denotes SLAVE DEVICE BUSY, 16 denotes timeout, 17 denotes frame format error, 18 denotes CRC error.

maskWrite

Modify the contents of a holding register using a AND mask OR mask parameters

Since R2019b

Syntax

ErrCode = maskWrite(obj, address, andMask, orMask)

ErrCode = maskWrite(obj, address, andMask, orMask, serverId)

Description

This function is used to set or clear individual bits in a specific holding register; a read/modify/write operation. This is done by using a combination of an AND mask, an OR mask, and the register's current contents.

The function’s algorithm is:

Result = (register value AND andMask) OR (orMask AND (NOT andMask))

Input Arguments

Output Arguments

scalar double. The reason of failure in mask-writing,  0 denotes success, 1 denotes ILLEGAL FUNCTION, 2 denotes ILLEGAL DATA ADDRESS, 3 denotes ILLEGAL DATA VALUE , 4 denotes SLAVE DEVICE FAILURE, 6 denotes SLAVE DEVICE BUSY, 16 denotes timeout, 17 denotes frame format error, 18 denotes CRC error.