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(transport,deviceAddress)
modbusClientObj = modbus(transport,deviceAddress,tcpipPort)
modbusClientObj = modbus(___,Name=Value)
modbusClientObj = modbus(transport,serialPort)
modbusClientObj = modbus(___,Name=Value)

Description

TCP/IP

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

The function creates the object and immediately connects to the Modbus server. If the server is unreachable, the function returns an error.

example

modbusClientObj = modbus(transport,deviceAddress,tcpipPort) additionally specifies tcpipPort as the remote port for the Modbus server. Default is 502, the reserved port for Modbus.

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

example

Serial RTU

modbusClientObj = modbus(transport,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

Physical transport layer for device communication, specified as a character vector or string. You must set the transport type as either "tcpip" or "serialrtu" to designate the protocol you want to use.

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

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

Data Types: char | string

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

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

Data Types: char | string

Remote port used by Modbus server, 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 of type double. 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, the connection is closed and reopened. For Serial RTU transport, the message is resent.

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 of type double. 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. 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, though 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, specified 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, the connection is closed and reopened.

Example: modbusObj.NumRetries = 10

Example:

>> modbusObj.NumRetries

ans =

     1

>> modbusObj.NumRetries = 5

modbusObj = 

Modbus TCPIP with properties:

    DeviceAddress: 'localhost'
             Port: 502
           Status: 'Connected'
       NumRetries: 5
          Timeout: 10 (seconds)
        ByteOrder: 'big-endian'
        WordOrder: 'big-endian'

Data Types: double

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

Example:

>> modbusObj.Timeout

ans =

     10

>> modbusObj.Timeout = 15

modbusObj = 

Modbus TCPIP with properties:

    DeviceAddress: 'localhost'
             Port: 502
           Status: 'Connected'
       NumRetries: 5
          Timeout: 15 (seconds)
        ByteOrder: 'big-endian'
        WordOrder: 'big-endian'

Data Types: double

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

Example:

>> modbusObj.ByteOrder

ans =

     'big-endian'

>> modbusObj.ByteOrder = "little-endian"

modbusObj = 

Modbus TCPIP with properties:

    DeviceAddress: 'localhost'
             Port: 502
           Status: 'Connected'
       NumRetries: 5
          Timeout: 10 (seconds)
        ByteOrder: 'little-endian'
        WordOrder: 'big-endian'

Data Types: char

Word order for register reads and writes that span multiple 16-bit registers, represented 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

ans =

     'big-endian'

>> modbusObj.WordOrder = "little-endian"

modbusObj = 

Modbus TCPIP with properties:

    DeviceAddress: 'localhost'
             Port: 502
           Status: 'Connected'
       NumRetries: 5
          Timeout: 10 (seconds)
        ByteOrder: 'big-endian'
        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, represented as a positive value of type double.

Example:

>> modbusObj.BaudRate

ans =

     9600

>> modbusObj.BaudRate = 38400

modbusObj = 

Modbus Serial RTU with properties:
 
             Port: 'COM5'
         BaudRate: 38400
         DataBits: 8
           Parity: 'none'
         StopBits: 1
           Status: 'Connected'
       NumRetries: 10
          Timeout: 60 (seconds)
        ByteOrder: 'big-endian'
        WordOrder: 'big-endian'

Data Types: double

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

Example:

>> modbusObj.DataBits

ans =

     8

>> modbusObj.DataBits = 6

modbusObj = 

Modbus Serial RTU with properties:
 
             Port: 'COM5'
         BaudRate: 9600
         DataBits: 6
           Parity: 'none'
         StopBits: 1
           Status: 'Connected'
       NumRetries: 10
          Timeout: 60 (seconds)
        ByteOrder: 'big-endian'
        WordOrder: 'big-endian'

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

ans =

     'none'

>> modbusObj.Parity = "even"

modbusObj = 

Modbus Serial RTU with properties:
 
             Port: 'COM5'
         BaudRate: 9600
         DataBits: 8
           Parity: 'even'
         StopBits: 1
           Status: 'Connected'
       NumRetries: 10
          Timeout: 60 (seconds)
        ByteOrder: 'big-endian'
        WordOrder: 'big-endian'

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, though 1 is typical for even/odd parity, and 2 for no parity.

Example:

>> modbusObj.StopBits

ans =

     1

>> modbusObj.StopBits = 2

modbusObj = 

Modbus Serial RTU with properties:
 
             Port: 'COM5'
         BaudRate: 9600
         DataBits: 8
           Parity: 'none'
         StopBits: 2
           Status: 'Connected'
       NumRetries: 10
          Timeout: 60 (seconds)
        ByteOrder: 'big-endian'
        WordOrder: 'big-endian'

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, the message is resent.

Example:

>> modbusObj.NumRetries

ans =

     1

>> modbusObj.NumRetries = 5

modbusObj = 

Modbus Serial RTU with properties:
 
             Port: 'COM5'
         BaudRate: 9600
         DataBits: 8
           Parity: 'none'
         StopBits: 1
           Status: 'Connected'
       NumRetries: 5
          Timeout: 60 (seconds)
        ByteOrder: 'big-endian'
        WordOrder: 'big-endian'

Data Types: double

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

Example:

>> modbusObj.Timeout

ans =

     10

>> modbusObj.Timeout = 15

modbusObj = 

Modbus Serial RTU with properties:
 
             Port: 'COM5'
         BaudRate: 9600
         DataBits: 8
           Parity: 'none'
         StopBits: 1
           Status: 'Connected'
       NumRetries: 5
          Timeout: 15 (seconds)
        ByteOrder: 'big-endian'
        WordOrder: 'big-endian'

Data Types: double

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

Example:

>> modbusObj.ByteOrder

ans =

     'big-endian'

>> modbusObj.ByteOrder = "little-endian"

modbusObj = 

Modbus Serial RTU with properties:
 
             Port: 'COM5'
         BaudRate: 9600
         DataBits: 8
           Parity: 'none'
         StopBits: 1
           Status: 'Connected'
       NumRetries: 5
          Timeout: 15 (seconds)
        ByteOrder: 'little-endian'
        WordOrder: 'big-endian'

Data Types: char

Word order for register reads and writes that span multiple 16-bit registers, represented 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

ans =

     'big-endian'

>> modbusObj.WordOrder = "little-endian"

modbusObj = 

Modbus Serial RTU with properties:
 
             Port: 'COM5'
         BaudRate: 9600
         DataBits: 8
           Parity: 'none'
         StopBits: 1
           Status: 'Connected'
       NumRetries: 5
          Timeout: 15 (seconds)
        ByteOrder: 'big-endian'
        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 object output shows both the arguments you set and the defaults.

When the transport is "serialrtu", you must specify a Port argument. This is the serial port that the Modbus server is connected to.

Create the Modbus object m specifying a 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 object output shows both the arguments you set and the defaults.

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