modbus

R2026b

Create Modbus interface object

expand all in page

Description

A Modbus® interface object represents a Modbus client in MATLAB® that connects to a Modbus server over TCP/IP or serial RTU protocols. Use this object to communicate with the server by reading or writing values to Modbus registers.

Creation

Syntax

modbusClientObj = modbus("tcpip",deviceAddress)
modbusClientObj = modbus("tcpip",deviceAddress,tcpipPort)
modbusClientObj = modbus(___,Name=Value)
modbusClientObj = modbus("serialrtu",serialPort)
modbusClientObj = modbus(___,Name=Value)

Description

TCP/IP

modbusClientObj = modbus("tcpip",deviceAddress) creates a Modbus interface object, modbusClientObj, over the transport type "tcpip". deviceAddress is the IP address or host name of the Modbus server.

The function creates the interface object and immediately connects to the Modbus server. If the server is unreachable, the function returns an error. The interface specifies the default remote port for use by the Modbus server, port 502.

example

modbusClientObj = modbus("tcpip",deviceAddress,tcpipPort) additionally specifies the remote port for the Modbus server.

modbusClientObj = modbus(___,Name=Value) specifies TCP/IP transport properties using optional name-value arguments.

example

Serial RTU

modbusClientObj = modbus("serialrtu",serialPort) creates a Modbus interface object, modbusClientObj, over the transport type "serialrtu" using the specified serialPort.

example

modbusClientObj = modbus(___,Name=Value) specifies Serial RTU transport properties using optional name-value arguments.

example

Input Arguments

expand all

IP address or host name of Modbus server, specified as a character vector or string. For TCP/IP transport, you must specify deviceAddress.

Example: modbusObj = modbus("tcpip","192.168.2.1")

Data Types: char | string

Remote port used by Modbus server for TCP/IP communication, specified as a positive scalar. If you do not specify a port, the default is 502.

Example: m = modbus("tcpip","192.168.2.1",308)

Data Types: double

Serial port used to connect to the Modbus server, specified as a character vector or string.

On Windows, serial ports are named COM1, COM2, and so on. On Linux, serial ports are represented as device files in the /dev/ directory, such as /dev/ttyS0 for built-in ports or /dev/ttyUSB0 for USB-to-serial adapters. On macOS, serial ports appear as device files in the /dev/ directory, typically named /dev/cu.usbserial-* or /dev/cu.usbmodem*.

Example: modbusObj = modbus("serialrtu","COM3")

Data Types: char | string

Name-Value Arguments

expand all

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.

Example: modbusObj = modbus("serialrtu","COM3",Timeout=20)

Maximum time in seconds to wait for a response from the Modbus server, specified as a positive value. The default is 10.

Example: modbusObj = modbus("tcpip","192.168.2.1",Timeout=20)

Example: modbusObj = modbus("serialrtu","COM3",Timeout=20)

Data Types: double

Number of retries to perform if there is no reply from the server after a timeout, specified as a positive integer.

For TCP/IP transport, a retry closes and reopens the connection. For Serial RTU transport, a retry resends the message.

Example: modbusObj = modbus("tcpip","192.168.2.1",NumRetries=5)

Example: modbusObj = modbus("serialrtu","COM3",NumRetries=5)

Data Types: double

Byte order of values written to or read from 16-bit registers, specified as "big-endian" or "little-endian". The default is "big-endian", as specified by the Modbus standard.

Tip

If you read incorrect values for multi-register data types (uint32, single, double), the issue could be either WordOrder or ByteOrder, try toggling each independently. If 16-bit register values appear byte-swapped, toggle ByteOrder.

Example: modbusObj = modbus("tcpip","192.168.2.1",ByteOrder="little-endian")

Example: modbusObj = modbus("serialrtu","COM3",ByteOrder="little-endian")

Data Types: char | string

Word order for register reads and writes that span multiple 16-bit registers, specified as "big-endian" or "little-endian". The default is "big-endian", as specified by the Modbus standard.

Tip

If you read incorrect values for multi-register data types (uint32, single, double), the issue could be either WordOrder or ByteOrder, try toggling each independently.

Example: modbusObj = modbus("tcpip","192.168.2.1",WordOrder="little-endian")

Example: modbusObj = modbus("serialrtu","COM3",WordOrder="little-endian")

Data Types: char | string

Bit transmission rate for serial port communication, specified as a positive value. Default is 9600 bits per second, but the actual required value is device-dependent.

Example: modbusObj = modbus("serialrtu","COM3",BaudRate=28800)

Data Types: double

Number of data bits to transmit, specified as either 5, 6, 7, or 8. The default is 8, which is the Modbus standard for Serial RTU.

Example: modbusObj = modbus("serialrtu","COM3",DataBits=6)

Data Types: double

Type of parity checking, specified as "none", "even", "odd", "mark", or "space". The actual required value is device-dependent. If set to the default of none, parity checking is not performed, and the parity bit is not transmitted.

Example: modbusObj = modbus("serialrtu","COM3",Parity="odd")

Data Types: char | string

Number of bits to indicate the end of data transmission, specified as 1 or 2. The actual required value is device-dependent. 1 is typical for even/odd parity, and 2 for no parity.

Example: modbusObj = modbus("serialrtu","COM3",StopBits=2)

Data Types: double

Output Arguments

expand all

Modbus client, returned either as an icomm.interface.modbus.tcpip.Modbus or icomm.interface.modbus.serialrtu.Modbus object, based on the transport layer used for communication.

Properties

expand all

TCP/IP

This property is read-only.

IP address or host name of Modbus server, represented as a character vector. This property takes its value from the deviceAddress input argument to modbus.

Example: '192.168.2.1'

Data Types: char

This property is read-only.

Remote port used by Modbus server, represented as a positive scalar. This property takes its value from the tcpipPort input argument to modbus. If you do not specify a port, the default is 502.

Example: 308

Data Types: double

This property is read-only.

Status of the Modbus client, represented as 'Disconnected' or 'Connected'. When you create a client, it is connected by default.

Example: 'Connected'

Number of retries to perform if there is no reply from the server after a timeout, represented as a positive integer. For TCP/IP transport, a retry closes and reopens the connection.

Example: modbusObj.NumRetries = 10

Data Types: double

Maximum time in seconds to wait for a response from the Modbus server, specified as a positive value.

Example: modbusObj.Timeout = 15

Data Types: double

Byte order of values written to or read from 16-bit registers, specified as 'big-endian' or 'little-endian'. To correctly interpret register values, configure the client byte order to match the Modbus server.

Example: modbusObj.ByteOrder = "little-endian"

Data Types: char

Word order for register reads and writes that span multiple 16-bit registers, specified as 'big-endian' or 'little-endian'. To correctly interpret multi‑register values, configure the client word order to match the Modbus server.

Example: modbusObj.WordOrder = "little-endian"

Data Types: char

Serial RTU

This property is read-only.

Serial port used to connect to the Modbus server, represented as a character vector. This property takes its value from the serialPort input argument to modbus.

Example: 'COM1'

Data Types: char

Bit transmission rate for serial port communication, specified as a positive value.

Example: modbusObj.BaudRate = 38400

Data Types: double

Number of data bits to transmit, specified as either 5, 6, 7, or 8.

Example: modbusObj.DataBits = 6

Data Types: double

Type of parity checking, specified as 'none', 'even', 'odd', 'mark', or 'space'. When the property value is set to none, parity checking is not performed, and the parity bit is not transmitted.

Example: modbusObj.Parity = "even"

Data Types: char | string

Number of bits to indicate the end of data transmission, specified as 1 or 2. The actual required value is device-dependent. 1 is typical for even/odd parity, and 2 for no parity.

Example: modbusObj.StopBits = 2

Data Types: double

This property is read-only.

Status of the Modbus client, represented as 'Disconnected' or 'Connected'. When you create a client, it is connected by default.

Example: 'Connected'

Number of retries to perform if there is no reply from the server after a timeout, represented as a positive integer. For Serial RTU transport, a retry resends the message.

Example: modbusObj.NumRetries = 5

Data Types: double

Maximum time in seconds to wait for a response from the Modbus server, represented as a positive value.

Example: modbusObj.Timeout = 15

Data Types: double

Byte order of values written to or read from 16-bit registers, specified as 'big-endian' or 'little-endian'. To correctly interpret register values, configure the client byte order to match the Modbus server.

Example: modbusObj.ByteOrder = "little-endian"

Data Types: char

Word order for register reads and writes that span multiple 16-bit registers, specified as 'big-endian' or 'little-endian'. To correctly interpret multi‑register values, configure the client word order to match the Modbus server.

Example: modbusObj.WordOrder = "little-endian"

Data Types: char

Object Functions

readRead data from Modbus server
writeWrite data to Modbus server
writeReadWrite and read holding registers in single Modbus transaction
maskWritePerform mask write operation on a holding register

Examples

collapse all

When the transport is TCP/IP, you must specify the IP address or host name of the Modbus server. You can optionally specify the remote port used by the Modbus server. Port defaults to 502, which is the reserved port for Modbus.

Create the Modbus object m using the host address shown and port of 308.

m = modbus("tcpip","192.168.2.1",308)
m = 

   Modbus TCPIP with properties:

    DeviceAddress: '192.168.2.1'
             Port: 308
           Status: 'Connected'
       NumRetries: 1
          Timeout: 10 (seconds)
        ByteOrder: 'big-endian'
        WordOrder: 'big-endian'

The client is now connected to the Modbus server. Communicate with the server using functions such as read and write.

When the transport is "serialrtu", you must specify a serialPort argument for the Modbus server.

Create the Modbus object m specifying a serial port of "COM3".

m = modbus("serialrtu","COM3")
m = 

Modbus Serial RTU with properties:

             Port: 'COM3'
         BaudRate: 9600
         DataBits: 8
           Parity: 'none'
         StopBits: 1
           Status: 'Connected'
       NumRetries: 1
          Timeout: 10 (seconds)
        ByteOrder: 'big-endian'
        WordOrder: 'big-endian'

The client is now connected to the Modbus server. Communicate with the server using functions such as read and write.

You can create the object using a name-value argument to set the properties such as Timeout. The Timeout property specifies the maximum time in seconds to wait for a response from the Modbus server, and the default is 10. You can change the value either during object creation or after you create the object. For a list of properties, see Name-Value Arguments.

Create a Modbus object using Serial RTU, but increase the Timeout to 20 seconds.

m = modbus("serialrtu","COM3",Timeout=20)
m = 

Modbus Serial RTU with properties:

             Port: 'COM3'
         BaudRate: 9600
         DataBits: 8
           Parity: 'none'
         StopBits: 1
           Status: 'Connected'
       NumRetries: 1
          Timeout: 20 (seconds)
        ByteOrder: 'big-endian'
        WordOrder: 'big-endian'

The object output reflects the Timeout property change.

Change the Timeout value to 30 seconds. You can use dot notation to change a property value after object creation.

m.Timeout = 30
m = 

Modbus Serial RTU with properties:

             Port: 'COM3'
         BaudRate: 9600
         DataBits: 8
           Parity: 'none'
         StopBits: 1
           Status: 'Connected'
       NumRetries: 1
          Timeout: 30 (seconds)
        ByteOrder: 'big-endian'
        WordOrder: 'big-endian'

Extended Capabilities

expand all

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

Version History

Introduced in R2017a

expand all

See Also

Functions

Blocks

Apps

Topics