Modbus (TCP/UDP/Serial)

Connection String Options

Modbus TCP

Name

Type

Default Value

Required

Description

Name

Modbus TCP

Code

modbus-tcp

Maven Dependency

 
<dependency>
  <groupId>org.apache.plc4x</groupId>
  <artifactId>plc4j-driver-modbus</artifactId>
  <version>pre-release</version>
</dependency>

Default Transport

tcp

Supported Transports

  • tcp

  • tls

  • tls-psk

  • udp

Config options:

request-timeout

INT

5000

Default timeout for all types of requests.

default-unit-identifier

INT

1

Unit-identifier or slave-id that identifies the target PLC (On RS485 multiple Modbus Devices can be listening). Defaults to 1.

ping-address

STRING

4x00001:BOOL

Simple address, that the driver will use to check, if the connection to a given device is active (Defaults to reading holding-register 1).

default-payload-byte-order

STRING

BIG_ENDIAN

Default encoding used for transporting register values (Defaults to BIG_ENDIAN).
Allowed values are:
- BIG_ENDIAN
- LITTLE_ENDIAN
- BIG_ENDIAN_BYTE_SWAP
- LITTLE_ENDIAN_BYTE_SWAP

Since: 0.13.0

max-coils-per-request

INT

2000

Maximum number of coils addressable in one request (Defaults to 2000)
Since: 0.13.0

max-registers-per-request

INT

125

Maximum number of registers addressable in one request (Defaults to 125)
Since: 0.13.0

Transport config options:

tcp

tcp.connect-timeout

INT

5000

tcp.read-timeout

INT

0

tcp.write-timeout

INT

0

tcp.tcp-no-delay

BOOLEAN

true

tcp.keep-alive

BOOLEAN

false

tcp.send-buffer-size

INT

81920

tcp.receive-buffer-size

INT

81920

tcp.local-address

STRING

tcp.local-port

INT

0

tls

tls.verify-ssl

BOOLEAN

true

tls.ignore-common-name

BOOLEAN

false

Tells the target to not validate the common name

tls.tls-version

STRING

TLS protocol version (e.g., 'TLSv1.2', 'TLSv1.3'). If not set, uses TLS 1.3 with fallback to TLS 1.2.

tls.keystore

STRING

Path to keystore (PKCS12/JKS) containing the client certificate and private key for mutual TLS.

tls.keystore-password

STRING

Password for the client keystore.

tls.keystore-type

STRING

Keystore type (e.g., 'PKCS12', 'JKS'). Defaults to PKCS12.

tls.log-session-keys

BOOLEAN

false

Log TLS session keys to the audit log in SSLKEYLOGFILE format for Wireshark decryption.

tls.connect-timeout

INT

5000

tls.read-timeout

INT

0

tls.write-timeout

INT

0

tls.tcp-no-delay

BOOLEAN

true

tls.keep-alive

BOOLEAN

false

tls.send-buffer-size

INT

81920

tls.receive-buffer-size

INT

81920

tls.local-address

STRING

tls.local-port

INT

0

tls-psk

tls-psk.psk-identity

STRING

PSK identity string for TLS-PSK authentication. Must be used together with psk-key.

tls-psk.psk-key

STRING

PSK key as hexadecimal string for TLS-PSK authentication. Must be used together with psk-identity.

tls-psk.log-session-keys

BOOLEAN

false

Log TLS session keys to the audit log in SSLKEYLOGFILE format for Wireshark decryption.

tls-psk.connect-timeout

INT

5000

tls-psk.read-timeout

INT

0

tls-psk.write-timeout

INT

0

tls-psk.tcp-no-delay

BOOLEAN

true

tls-psk.keep-alive

BOOLEAN

false

tls-psk.send-buffer-size

INT

81920

tls-psk.receive-buffer-size

INT

81920

tls-psk.local-address

STRING

tls-psk.local-port

INT

0

udp

udp.local-address

STRING

Local address to bind to. If not set, binds to all interfaces.

udp.local-port

INT

0

Local port to bind to. 0 uses ephemeral port.

udp.read-timeout

INT

0

Socket read timeout in milliseconds. 0 means no timeout.

udp.max-packet-size

INT

65507

Maximum UDP packet size in bytes.

udp.send-buffer-size

INT

0

Send buffer size in bytes. 0 uses system default.

udp.receive-buffer-size

INT

0

Receive buffer size in bytes. 0 uses system default.

udp.broadcast

BOOLEAN

false

Enable SO_BROADCAST for sending broadcast packets.

udp.reuse-address

BOOLEAN

false

Enable SO_REUSEADDR to allow multiple bindings to the same address/port.

udp.share-socket

BOOLEAN

false

Share the underlying UDP socket across multiple transport instances. When true, instances with the same localAddress:localPort will share a socket. This is useful for protocols where multiple logical connections share one UDP port.

udp.multicast-ttl

INT

1

Time-to-live for multicast packets (1-255).

Modbus RTU

Name

Type

Default Value

Required

Description

Name

Modbus RTU

Code

modbus-rtu

Maven Dependency

 
<dependency>
  <groupId>org.apache.plc4x</groupId>
  <artifactId>plc4j-driver-modbus</artifactId>
  <version>pre-release</version>
</dependency>

Default Transport

serial

Supported Transports

  • serial

  • tcp

  • tls

  • tls-psk

  • udp

Config options:

request-timeout

INT

5000

Default timeout for all types of requests.

default-unit-identifier

INT

1

Unit-identifier or slave-id that identifies the target PLC (On RS485 multiple Modbus Devices can be listening). Defaults to 1.

ping-address

STRING

4x00001:BOOL

Simple address, that the driver will use to check, if the connection to a given device is active (Defaults to reading holding-register 1).

default-payload-byte-order

STRING

BIG_ENDIAN

Default encoding used for transporting register values (Defaults to BIG_ENDIAN).
Allowed values are:
- BIG_ENDIAN
- LITTLE_ENDIAN
- BIG_ENDIAN_BYTE_SWAP
- LITTLE_ENDIAN_BYTE_SWAP

Since: 0.13.0

max-coils-per-request

INT

2000

Maximum number of coils addressable in one request (Defaults to 2000)
Since: 0.13.0

max-registers-per-request

INT

125

Maximum number of registers addressable in one request (Defaults to 125)
Since: 0.13.0

Transport config options:

serial

serial.baud-rate

INT

9600

Baud rate (bits per second)

serial.data-bits

INT

8

Number of data bits (5, 6, 7, or 8)

serial.stop-bits

INT

1

Number of stop bits (1 or 2)

serial.parity

STRING

NONE

Parity: NONE, ODD, EVEN, MARK, SPACE

serial.flow-control

STRING

NONE

Flow control: NONE, RTS_CTS, XON_XOFF, RTS_CTS_XON_XOFF

serial.read-timeout

INT

1000

Read timeout in milliseconds. 0 means blocking read.

serial.write-timeout

INT

1000

Write timeout in milliseconds.

serial.dtr

BOOLEAN

false

Enable DTR (Data Terminal Ready) signal

serial.rts

BOOLEAN

false

Enable RTS (Request To Send) signal

serial.reuse-port

BOOLEAN

false

Reuse the underlying serial port across multiple transport instances. When true, instances with the same port will share a connection. This is useful for protocols where multiple logical connections share one serial port.

serial.receive-buffer-size

INT

4096

Receive buffer size in bytes. 0 uses system default.

serial.send-buffer-size

INT

4096

Send buffer size in bytes. 0 uses system default.

serial.break-enabled

BOOLEAN

false

Enable break signal

serial.interframe-delay

INT

0

Interframe delay in milliseconds for protocols that need spacing between messages. Only applies when reusePort is true.

tcp

tcp.connect-timeout

INT

5000

tcp.read-timeout

INT

0

tcp.write-timeout

INT

0

tcp.tcp-no-delay

BOOLEAN

true

tcp.keep-alive

BOOLEAN

false

tcp.send-buffer-size

INT

81920

tcp.receive-buffer-size

INT

81920

tcp.local-address

STRING

tcp.local-port

INT

0

tls

tls.verify-ssl

BOOLEAN

true

tls.ignore-common-name

BOOLEAN

false

Tells the target to not validate the common name

tls.tls-version

STRING

TLS protocol version (e.g., 'TLSv1.2', 'TLSv1.3'). If not set, uses TLS 1.3 with fallback to TLS 1.2.

tls.keystore

STRING

Path to keystore (PKCS12/JKS) containing the client certificate and private key for mutual TLS.

tls.keystore-password

STRING

Password for the client keystore.

tls.keystore-type

STRING

Keystore type (e.g., 'PKCS12', 'JKS'). Defaults to PKCS12.

tls.log-session-keys

BOOLEAN

false

Log TLS session keys to the audit log in SSLKEYLOGFILE format for Wireshark decryption.

tls.connect-timeout

INT

5000

tls.read-timeout

INT

0

tls.write-timeout

INT

0

tls.tcp-no-delay

BOOLEAN

true

tls.keep-alive

BOOLEAN

false

tls.send-buffer-size

INT

81920

tls.receive-buffer-size

INT

81920

tls.local-address

STRING

tls.local-port

INT

0

tls-psk

tls-psk.psk-identity

STRING

PSK identity string for TLS-PSK authentication. Must be used together with psk-key.

tls-psk.psk-key

STRING

PSK key as hexadecimal string for TLS-PSK authentication. Must be used together with psk-identity.

tls-psk.log-session-keys

BOOLEAN

false

Log TLS session keys to the audit log in SSLKEYLOGFILE format for Wireshark decryption.

tls-psk.connect-timeout

INT

5000

tls-psk.read-timeout

INT

0

tls-psk.write-timeout

INT

0

tls-psk.tcp-no-delay

BOOLEAN

true

tls-psk.keep-alive

BOOLEAN

false

tls-psk.send-buffer-size

INT

81920

tls-psk.receive-buffer-size

INT

81920

tls-psk.local-address

STRING

tls-psk.local-port

INT

0

udp

udp.local-address

STRING

Local address to bind to. If not set, binds to all interfaces.

udp.local-port

INT

0

Local port to bind to. 0 uses ephemeral port.

udp.read-timeout

INT

0

Socket read timeout in milliseconds. 0 means no timeout.

udp.max-packet-size

INT

65507

Maximum UDP packet size in bytes.

udp.send-buffer-size

INT

0

Send buffer size in bytes. 0 uses system default.

udp.receive-buffer-size

INT

0

Receive buffer size in bytes. 0 uses system default.

udp.broadcast

BOOLEAN

false

Enable SO_BROADCAST for sending broadcast packets.

udp.reuse-address

BOOLEAN

false

Enable SO_REUSEADDR to allow multiple bindings to the same address/port.

udp.share-socket

BOOLEAN

false

Share the underlying UDP socket across multiple transport instances. When true, instances with the same localAddress:localPort will share a socket. This is useful for protocols where multiple logical connections share one UDP port.

udp.multicast-ttl

INT

1

Time-to-live for multicast packets (1-255).

Modbus ASCII

Name

Type

Default Value

Required

Description

Name

Modbus ASCII

Code

modbus-ascii

Maven Dependency

 
<dependency>
  <groupId>org.apache.plc4x</groupId>
  <artifactId>plc4j-driver-modbus</artifactId>
  <version>pre-release</version>
</dependency>

Default Transport

serial

Supported Transports

  • serial

  • tcp

  • tls

  • tls-psk

  • udp

Config options:

request-timeout

INT

5000

Default timeout for all types of requests.

default-unit-identifier

INT

1

Unit-identifier or slave-id that identifies the target PLC (On RS485 multiple Modbus Devices can be listening). Defaults to 1.

ping-address

STRING

4x00001:BOOL

Simple address, that the driver will use to check, if the connection to a given device is active (Defaults to reading holding-register 1).

default-payload-byte-order

STRING

BIG_ENDIAN

Default encoding used for transporting register values (Defaults to BIG_ENDIAN).
Allowed values are:
- BIG_ENDIAN
- LITTLE_ENDIAN
- BIG_ENDIAN_BYTE_SWAP
- LITTLE_ENDIAN_BYTE_SWAP

Since: 0.13.0

max-coils-per-request

INT

2000

Maximum number of coils addressable in one request (Defaults to 2000)
Since: 0.13.0

max-registers-per-request

INT

125

Maximum number of registers addressable in one request (Defaults to 125)
Since: 0.13.0

Transport config options:

serial

serial.baud-rate

INT

9600

Baud rate (bits per second)

serial.data-bits

INT

8

Number of data bits (5, 6, 7, or 8)

serial.stop-bits

INT

1

Number of stop bits (1 or 2)

serial.parity

STRING

NONE

Parity: NONE, ODD, EVEN, MARK, SPACE

serial.flow-control

STRING

NONE

Flow control: NONE, RTS_CTS, XON_XOFF, RTS_CTS_XON_XOFF

serial.read-timeout

INT

1000

Read timeout in milliseconds. 0 means blocking read.

serial.write-timeout

INT

1000

Write timeout in milliseconds.

serial.dtr

BOOLEAN

false

Enable DTR (Data Terminal Ready) signal

serial.rts

BOOLEAN

false

Enable RTS (Request To Send) signal

serial.reuse-port

BOOLEAN

false

Reuse the underlying serial port across multiple transport instances. When true, instances with the same port will share a connection. This is useful for protocols where multiple logical connections share one serial port.

serial.receive-buffer-size

INT

4096

Receive buffer size in bytes. 0 uses system default.

serial.send-buffer-size

INT

4096

Send buffer size in bytes. 0 uses system default.

serial.break-enabled

BOOLEAN

false

Enable break signal

serial.interframe-delay

INT

0

Interframe delay in milliseconds for protocols that need spacing between messages. Only applies when reusePort is true.

tcp

tcp.connect-timeout

INT

5000

tcp.read-timeout

INT

0

tcp.write-timeout

INT

0

tcp.tcp-no-delay

BOOLEAN

true

tcp.keep-alive

BOOLEAN

false

tcp.send-buffer-size

INT

81920

tcp.receive-buffer-size

INT

81920

tcp.local-address

STRING

tcp.local-port

INT

0

tls

tls.verify-ssl

BOOLEAN

true

tls.ignore-common-name

BOOLEAN

false

Tells the target to not validate the common name

tls.tls-version

STRING

TLS protocol version (e.g., 'TLSv1.2', 'TLSv1.3'). If not set, uses TLS 1.3 with fallback to TLS 1.2.

tls.keystore

STRING

Path to keystore (PKCS12/JKS) containing the client certificate and private key for mutual TLS.

tls.keystore-password

STRING

Password for the client keystore.

tls.keystore-type

STRING

Keystore type (e.g., 'PKCS12', 'JKS'). Defaults to PKCS12.

tls.log-session-keys

BOOLEAN

false

Log TLS session keys to the audit log in SSLKEYLOGFILE format for Wireshark decryption.

tls.connect-timeout

INT

5000

tls.read-timeout

INT

0

tls.write-timeout

INT

0

tls.tcp-no-delay

BOOLEAN

true

tls.keep-alive

BOOLEAN

false

tls.send-buffer-size

INT

81920

tls.receive-buffer-size

INT

81920

tls.local-address

STRING

tls.local-port

INT

0

tls-psk

tls-psk.psk-identity

STRING

PSK identity string for TLS-PSK authentication. Must be used together with psk-key.

tls-psk.psk-key

STRING

PSK key as hexadecimal string for TLS-PSK authentication. Must be used together with psk-identity.

tls-psk.log-session-keys

BOOLEAN

false

Log TLS session keys to the audit log in SSLKEYLOGFILE format for Wireshark decryption.

tls-psk.connect-timeout

INT

5000

tls-psk.read-timeout

INT

0

tls-psk.write-timeout

INT

0

tls-psk.tcp-no-delay

BOOLEAN

true

tls-psk.keep-alive

BOOLEAN

false

tls-psk.send-buffer-size

INT

81920

tls-psk.receive-buffer-size

INT

81920

tls-psk.local-address

STRING

tls-psk.local-port

INT

0

udp

udp.local-address

STRING

Local address to bind to. If not set, binds to all interfaces.

udp.local-port

INT

0

Local port to bind to. 0 uses ephemeral port.

udp.read-timeout

INT

0

Socket read timeout in milliseconds. 0 means no timeout.

udp.max-packet-size

INT

65507

Maximum UDP packet size in bytes.

udp.send-buffer-size

INT

0

Send buffer size in bytes. 0 uses system default.

udp.receive-buffer-size

INT

0

Receive buffer size in bytes. 0 uses system default.

udp.broadcast

BOOLEAN

false

Enable SO_BROADCAST for sending broadcast packets.

udp.reuse-address

BOOLEAN

false

Enable SO_REUSEADDR to allow multiple bindings to the same address/port.

udp.share-socket

BOOLEAN

false

Share the underlying UDP socket across multiple transport instances. When true, instances with the same localAddress:localPort will share a socket. This is useful for protocols where multiple logical connections share one UDP port.

udp.multicast-ttl

INT

1

Time-to-live for multicast packets (1-255).

Supported Operations

Name Value Description

Supported Operations

read

write

Individual Resource Address Format

Connection String

Modbus has the following connection string format:-

modbus-tcp:{transport}://{ip-address}:{port}?{options}

An example connection string would look like:-

modbus-tcp:tcp://127.0.0.1:502

Note the transport, port and option fields are optional.

General Format

In general all Modbus addresses have this format:

{memory-Area}{start-address}:{data-type}[{array-size}]:{name-value-tag-options}

If the array-size part is omitted, the size-default of 1 is assumed. If the data-type part is omitted, it defaults to BOOL for Coils and Discrete Inputs and INT for input, holding and extended registers. If the name-value-tag-options part is omitted, simply no configuration fine-tuning is applied.

Additionally address can contain tag configuration:

{unit-id: 123}

Specifying this value overrides value of default-unit-id parameter specified at the connection string.

{byte-order: 'LITTLE_ENDIAN'}

With this, can the default byte-order be overridden on a per-tag basis. If not provided the default-byte-order from the connection string is used, or BIG_ENDIAN, if this is also not provided.

Memory Areas

There are a number of memory areas defined in the Modbus specification.

  • Discrete Input Area

  • Coil Area

  • Input Register Area

  • Holding Register

  • Extended Register Area

Name Memory Area Aliases Description Bit-Size Permissions Starting Address

Discrete Input

discrete-input: or 1 or 1x

Boolean input value, usually representing a binary input to the PLC

1

Read Only

1

Coil

coil: or 0 or 0x

Boolean value, usually representing a binary output from the PLC

1

Read/Write

1

Input Register

input-register: or 3 or 3x

Short input value, usually representing an analog input to the PLC

16

Read Only

1

Holding Register

holding-register: or 4 or 4x

Short value, usually representing an analog output from the PLC

16

Read/Write

1

Extended Register

extended-register: or 6 or 6x

Short value,

16

Read/Write

0

Initially the Modbus format allowed up to 10000 address to be specified or the discrete inputs, coils, input registers and holding registers. Later on, this was expanded to allow up 65536 address within each memory area (except the extended register area). When using the long address format i.e. input-registers:1 the addresses between 1 and 65535 are able to be specified. When using the shorter versions there are two formats available i.e. 30001 and 300001. With the shorter format 3XXXX being limited to between 30001 and 39999, while the longer format 3XXXXX being limited to between 300001 and 365535. These memory areas all start at address 1.

For the extended register area the addresses 0-99999 are able to be specified. These registers are mapped to file records with a length of 10000. Address 600000 corresponds to the first address in file record 0. Address 610000 is then the first address in the second file record and so on. It is noted that there is generally only 10 file records (600000 thru to 699999) however the spec allows for 65536 file records. Using the extended-register: format you are able to reference all of these, if the shorter format is used then it is limited to 699999. This memory area starts at address 0.

Data Types

The following data types are supported

  • BOOL (boolean)

  • SINT (int 8)

  • USINT (uint 8)

  • BYTE (uint 8)

  • INT (int 16)

  • UINT (uint 16)

  • WORD (uint 16)

  • DINT (int 32)

  • UDINT (uint 32)

  • DWORD (uint 32)

  • LINT (int 64)

  • ULINT (uint 64)

  • LWORD (uint 64)

  • REAL (float)

  • LREAL (double)

  • CHAR (char)

  • WCHAR (2 byte char)

Some useful tips

Most memory areas start at address 1, except for the extended register area which starts at 0. These are both mapped to 0x0000 when it is sent in the Modbus protocol.

The input, holding and extended registers consist of 16-bit registers while the discrete input and coil areas consist of bits.

The following Modbus function codes are supported:-

  • 0x01 (Read Coils)

  • 0x02 (Read Discrete Inputs)

  • 0x03 (Read Holding Registers)

  • 0x04 (Read Input Registers)

  • 0x05 (Write Single Coil)

  • 0x06 (Write Single Register)

  • 0x0F (Write Multiple Coils)

  • 0x10 (Write Multiple Registers)

  • 0x14 (Read File Record)(Extended Register Read)

  • 0x15 (Write File Record)(Extended Register Write)

Examples

To read 10 holding registers starting at address 20 and parse as Unsigned Integers the following examples are all valid.

  • holding-register:20:UINT[10]

  • 400020:UINT[10]

  • 4x00020:UINT[10]

  • 40020:UINT[10]

  • 4x0020:UINT[10]

To read 1 holding register at address 5678 the following examples are valid.

  • holding-register:5678

  • 405678

  • 4x05678

  • 45678

  • 4x5678

To read 1 holding register of unit 10 at address 5678 the following examples are valid.

  • holding-register:5678{unit-id: 10}

  • 405678{unit-id: 10}

  • 4x05678{unit-id: 10}

  • 45678{unit-id: 10}

  • 4x5678{unit-id: 10}

To read 10 extended registers starting at address 50 the following examples are valid.

  • extended-register:50[10]

  • 600050[10]

  • 6x00050[10]

  • 60050[10]

  • 6x0050[10]

This corresponds to addresses 50-59 in file record 1.

To read 10 extended registers starting at address 9995 the following examples are valid.

  • extended-register:9995[10]

  • 609995[10]

  • 6x09995[10]

  • 69995[10]

  • 6x9995[10]

This corresponds to addresses 9995-9999 in file record 1 and addresses 0-5 in file record 2. Note that this request is split into 2 sub requests in the Modbus protocol.