modbus

Create Modbus object

Syntax

m = modbus(Transport,DeviceAddress)

m = modbus(Transport,DeviceAddress,Port)

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

m = modbus(Transport,Port)

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

Description

m = modbus(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 = modbus(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 = modbus(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 10.

m = modbus(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 server is connected to, such as 'COM3'.

m = modbus(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.

Examples

Create Object Using TCP/IP Transport

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: 'open'
       NumRetries: 1
          Timeout: 10 (seconds)
        ByteOrder: 'big-endian'
        WordOrder: 'big-endian'

The object output shows both the arguments you set and the defaults.

Create Object Using Serial RTU Transport

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: 'open'
       NumRetries: 1
          Timeout: 10 (seconds)
        ByteOrder: 'big-endian'
        WordOrder: 'big-endian'

The object output shows arguments you set and defaults that are used automatically.

Create Object and Set a Property

You can create the object using a name-value pair 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 the list and description of properties you can set for both transport types, see Configure Properties for Modbus Communication.

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: 'open'
       NumRetries: 1
          Timeout: 20 (seconds)
        ByteOrder: 'big-endian'
        WordOrder: 'big-endian'

The object output reflects the Timeout property change.

Input Arguments

Transport — Physical transport layer for device communication

character vector | string

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.

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

Data Types: char

DeviceAddress — IP address or host name of Modbus server

character vector | string

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 = modbus('tcpip','192.168.2.1')

Data Types: char

Port — Remote port used by Modbus server

502 (default) | 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.

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

Data Types: double

Port — Serial port Modbus server is connected to

character vector | string

Serial port Modbus server 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.

Example: m = modbus('serialrtu','COM3')

Data Types: char

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.

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

Example: m = modbus('serialrtu','COM3','Timeout',20)

There are a number of name-value pairs that can be used when you create the modbus object, including the two shown here. Some can only be used with either TCP/IP or Serial RTU, and some can be used with both transport types. For a list of all the properties and how to set them both during and after object creation, see Configure Properties for Modbus Communication.

Timeout — Maximum time in seconds to wait for a response from the Modbus server

10 (default) | double

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 10. You can change the value either during object creation or after you create the object.

Example: m = modbus('serialrtu','COM3','Timeout',20)

Data Types: double

NumRetries — Number of retries to perform if there is no reply from the server after a timeout

double

Number of retries to perform if there is no reply from the server after a timeout, specified as the comma-separated pair consisting of 'NumRetries' and a positive value of type double. If using the Serial RTU transport, the message is resent. If using the TCP/IP transport, the connection is closed and reopened. You can change the value either during object creation, or after you create the object.

Example: m = modbus('serialrtu','COM3','NumRetries',5)

Data Types: double

Extended Capabilities

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

Version History

Introduced in R2017a

R2022a: Moved to Industrial Communication Toolbox from Instrument Control Toolbox

Before R2022a, the Modbus functionality, including this function, was part of the Instrument Control Toolbox™ product.