easymodbus4j

https://github.com/zengfr/easymodbus4j
Admin
A high-performance Java implementation of the Modbus protocol using Netty, supporting both TCP and...
Tokens:11,438
Snippets:84
Trust Score:8
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### TCP Client Master Quick-Start Example

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

This Java code sets up a Modbus TCP client in master mode. It connects to a specified IP address and port, then schedules asynchronous read and write operations to a Modbus slave device. Ensure the Modbus slave is accessible at the given IP and port.

```java
import com.github.zengfr.easymodbus4j.ModbusConfs;
import com.github.zengfr.easymodbus4j.client.ModbusClient4TcpMaster;
import com.github.zengfr.easymodbus4j.client.ModbusClientTcpFactory;
import com.github.zengfr.easymodbus4j.common.util.ScheduledUtil;
import com.github.zengfr.easymodbus4j.handle.impl.ModbusMasterResponseHandler;
import com.github.zengfr.easymodbus4j.processor.ModbusMasterResponseProcessor;
import com.github.zengfr.easymodbus4j.sender.ChannelSender;
import com.github.zengfr.easymodbus4j.sender.ChannelSenderFactory;
import io.netty.channel.Channel;

public class QuickStartClient4Master {

    public static void main(String[] args) throws Exception {
        ModbusConfs.MASTER_SHOW_DEBUG_LOG = true;

        ModbusMasterResponseProcessor processor = new MyMasterResponseProcessor((short) 0);
        ModbusMasterResponseHandler responseHandler = new ModbusMasterResponseHandler(processor);

        ModbusClient4TcpMaster client = 
            ModbusClientTcpFactory.getInstance().createClient4Master("192.168.1.10", 502, responseHandler);

        // Wait for async Netty connect
        Thread.sleep(3000);

        // Schedule polling every 5 seconds
        ScheduledUtil.getInstance().scheduleAtFixedRate(() -> {
            Channel ch = client.getChannel();
            if (ch == null || !ch.isActive() || !ch.isWritable()) return;

            ChannelSender sender = ChannelSenderFactory.getInstance().get(ch);
            try {
                sender.readCoilsAsync(0, 8);                      // FC1
                sender.readHoldingRegistersAsync(0, 10);          // FC3
                sender.writeSingleRegister(100, 42);              // FC6
            } catch (Exception e) {
                e.printStackTrace();
            }
        }, 5000);
    }
}

```

--------------------------------

### Custom Modbus Client/Server in Java

Source: https://github.com/zengfr/easymodbus4j/blob/master/README.md

Create and configure custom Modbus clients and servers by providing a ModbusChannelInitializer. This allows for advanced customization of the Modbus communication setup.

```java
ModbusChannelInitializer modbusChannelInitializer=...;
ModbusServerTcpFactory.getInstance().createServer4Master(port,modbusChannelInitializer);
```

--------------------------------

### Implement Modbus Master/Slave Interfaces

Source: https://github.com/zengfr/easymodbus4j/wiki/QuickStart

Implement ResponseHandler for master mode and RequestHandler for slave mode. Refer to the example Java files for detailed implementation.

```java
if masterImplements ResponseHandler interface see easymodbus4j-example:ModbusMasterResponseHandler.java 
if slaveImplements RequestHandler interface see easymodbus4j-example:ModbusSlaveRequestHandler.java
```

--------------------------------

### Scheduled Modbus Requests via autoSend.txt

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

Configure recurring Modbus requests by listing them in `autoSend.txt`. Each line specifies the function, address, and values. Lines starting with '#' are ignored.

```text
# autoSend.txt — one request per line: function|address|values
# Lines starting with # are ignored

readCoilsAsync|81|1
readHoldingRegistersAsync|33|17
readInputRegisters|49|18
readDiscreteInputs|65|16
writeSingleCoil|17|F
writeSingleRegister|18|22
writeMultipleCoils|25|T,F,T,F,T,T
writeMultipleRegisters|24|1,3,5,7,14

# Commented-out examples:
#writeSingleCoil|19|T
#writeSingleRegister|97|33
```

--------------------------------

### Send Modbus Requests

Source: https://github.com/zengfr/easymodbus4j/wiki/QuickStart

Obtain a ChannelSender to send various Modbus read and write requests. Refer to ModbusMasterResponseHandler.java for logging examples.

```java
ChannelSender sender = ChannelSenderFactory.getInstance().get(channel);
sender.readCoils(...)
sender.readDiscreteInputs(...)
sender.writeSingleRegister(...)
```

```java
ModbusFrameUtil.showFrameLog(logger, channel, frame);
```

--------------------------------

### Get Modbus Response as ByteArray in Java

Source: https://github.com/zengfr/easymodbus4j/blob/master/README.md

Extract the response data as a byte array for custom decoding. This is useful when you need to process the raw response bytes, for example, from a ReadDiscreteInputsResponse.

```java
public void processResponseFrame(Channel channel, int unitId, AbstractFunction reqFunc, ModbusFunction respFunc) {
			if (respFunc instanceof ReadDiscreteInputsResponse) {
				ReadDiscreteInputsResponse resp = (ReadDiscreteInputsResponse) respFunc;
				byte[] resutArray = resp.getInputStatus().toByteArray();
			}
	};
```

--------------------------------

### Create Modbus Server and Client Instances

Source: https://github.com/zengfr/easymodbus4j/wiki/QuickStart

Instantiate Modbus server and client objects using the respective factories based on the desired mode (master/slave).

```java
modbusServer = ModbusServerFactory.getInstance().createServer4Master(port, responseHandler);
modbusClient = ModbusClientFactory.getInstance().createClient4Slave(port, requestHandler);

modbusClient = ModbusClientFactory.getInstance().createClient4Master(host, port, responseHandler);
modbusServer = ModbusServerFactory.getInstance().createServer4Slave(port, requestHandler);
```

--------------------------------

### Create Modbus TCP Server (Master Mode)

Source: https://github.com/zengfr/easymodbus4j/blob/master/README.md

Instantiate a Modbus TCP server acting as a master. Requires a ResponseHandler implementation.

```java
modbusServer = ModbusServerTcpFactory.getInstance().createServer4Master(port, responseHandler);
```

--------------------------------

### TCP Server in Master Mode Quick-Start

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

This Java code sets up a Modbus TCP server that acts as a master. It listens for slave connections and periodically polls them for data. Ensure the ModbusConfs.MASTER_SHOW_DEBUG_LOG is set to true for debugging.

```java
import com.github.zengfr.easymodbus4j.ModbusConfs;
import com.github.zengfr.easymodbus4j.common.util.ScheduledUtil;
import com.github.zengfr.easymodbus4j.handle.impl.ModbusMasterResponseHandler;
import com.github.zengfr.easymodbus4j.processor.ModbusMasterResponseProcessor;
import com.github.zengfr.easymodbus4j.sender.ChannelSender;
import com.github.zengfr.easymodbus4j.sender.ChannelSenderFactory;
import com.github.zengfr.easymodbus4j.server.ModbusServer4TcpMaster;
import com.github.zengfr.easymodbus4j.server.ModbusServerTcpFactory;
import io.netty.channel.Channel;
import java.util.Collection;

public class QuickStartServer4Master {

    public static void main(String[] args) throws Exception {
        ModbusConfs.MASTER_SHOW_DEBUG_LOG = true;

        ModbusMasterResponseProcessor processor = new MyMasterResponseProcessor((short) 0);
        ModbusMasterResponseHandler responseHandler = new ModbusMasterResponseHandler(processor);

        ModbusServer4TcpMaster server = 
            ModbusServerTcpFactory.getInstance().createServer4Master(502, responseHandler);

        // Give slave devices time to connect
        Thread.sleep(3000);

        ScheduledUtil.getInstance().scheduleAtFixedRate(() -> {
            Collection<Channel> channels = server.getChannels();
            for (Channel ch : channels) {
                if (ch == null || !ch.isActive() || !ch.isWritable()) continue;
                ChannelSender sender = ChannelSenderFactory.getInstance().get(ch);
                try {
                    sender.readCoilsAsync(0, 4);                  // FC1
                    sender.readInputRegisters(0, 8);              // FC4
                } catch (Exception e) {
                    e.printStackTrace();
                }
            }
        }, 5000);
    }
}

```

--------------------------------

### Create Modbus RTU Server (Master Mode)

Source: https://github.com/zengfr/easymodbus4j/blob/master/README.md

Instantiate a Modbus RTU server acting as a master. Requires a ResponseHandler implementation.

```java
modbusServer = ModbusServerRtuFactory.getInstance().createServer4Master(port, responseHandler);
```

--------------------------------

### Create Modbus TCP Client (Master Mode)

Source: https://github.com/zengfr/easymodbus4j/blob/master/README.md

Instantiate a Modbus TCP client acting as a master. Requires a ResponseHandler implementation.

```java
modbusClient = ModbusClientTcpFactory.getInstance().createClient4Master(host, port, responseHandler);
```

--------------------------------

### Configure Modbus Runtime Settings

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

Adjust global configuration flags for logging, timeouts, and frame validation. Ensure necessary imports are present.

```java
import com.github.zengfr.easymodbus4j.ModbusConfs;
import com.github.zengfr.easymodbus4j.ModbusConsts;

// Enable verbose frame logging for master and slave sides
ModbusConfs.MASTER_SHOW_DEBUG_LOG = true;
ModbusConfs.SLAVE_SHOW_DEBUG_LOG  = false;

// Drop channels idle for more than 60 seconds
ModbusConfs.IDLE_TIMEOUT_SECOND = 60;

// Ignore malformed frames whose reported length exceeds this threshold
ModbusConfs.RESPONS_EFRAME_IGNORE_LENGTH_THRESHOLD = 256;

// Override the default Modbus TCP port (502)
// ModbusConfs.DEFAULT_MODBUS_PORT = 502;

// Override the unit identifier sent in every request
ModbusConsts.DEFAULT_UNIT_IDENTIFIER = 1;

// Set a custom heartbeat string (sent on idle channels)
ModbusConsts.HEARTBEAT = "";
```

--------------------------------

### Create Modbus TCP Server (Slave Mode)

Source: https://github.com/zengfr/easymodbus4j/blob/master/README.md

Instantiate a Modbus TCP server acting as a slave. Requires a RequestHandler implementation.

```java
modbusServer = ModbusServerTcpFactory.getInstance().createServer4Slave(port, requestHandler);
```

--------------------------------

### Create Modbus RTU Client (Master Mode)

Source: https://github.com/zengfr/easymodbus4j/blob/master/README.md

Instantiate a Modbus RTU client acting as a master. Requires a ResponseHandler implementation.

```java
modbusClient = ModbusClientRtuFactory.getInstance().createClient4Master(host, port, responseHandler);
```

--------------------------------

### Create Modbus RTU Server (Slave Mode)

Source: https://github.com/zengfr/easymodbus4j/blob/master/README.md

Instantiate a Modbus RTU server acting as a slave. Requires a RequestHandler implementation.

```java
modbusServer = ModbusServerRtuFactory.getInstance().createServer4Slave(port, requestHandler);
```

--------------------------------

### Create Modbus TCP Client (Master Role)

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

Use ModbusClientTcpFactory to create a TCP client for the master role. Ensure the async connection establishes before sending requests.

```java
import com.github.zengfr.easymodbus4j.client.ModbusClient4TcpMaster;
import com.github.zengfr.easymodbus4j.client.ModbusClientTcpFactory;
import com.github.zengfr.easymodbus4j.handle.impl.ModbusMasterResponseHandler;
import com.github.zengfr.easymodbus4j.processor.ModbusMasterResponseProcessor;
import com.github.zengfr.easymodbus4j.ModbusConfs;

// --- Master role: client connects to a remote slave device ---
ModbusConfs.MASTER_SHOW_DEBUG_LOG = true;

ModbusMasterResponseProcessor processor = new MyMasterResponseProcessor((short) 0);
ModbusMasterResponseHandler responseHandler = new ModbusMasterResponseHandler(processor);

ModbusClient4TcpMaster client = 
    ModbusClientTcpFactory.getInstance().createClient4Master("192.168.1.10", 502, responseHandler);

// Wait for the async connection to establish before sending
Thread.sleep(3000);
```

--------------------------------

### Create Modbus TCP Client (Slave Mode)

Source: https://github.com/zengfr/easymodbus4j/blob/master/README.md

Instantiate a Modbus TCP client acting as a slave. Requires a RequestHandler implementation.

```java
modbusClient = ModbusClientTcpFactory.getInstance().createClient4Slave(host,port, requestHandler);
```

--------------------------------

### ModbusClientTcpFactory - TCP Client Creation

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

Demonstrates how to create Modbus TCP clients for both master and slave roles using the ModbusClientTcpFactory. The factory provides methods to establish connections to remote Modbus devices or to act as a Modbus server endpoint.

```APIDOC
## ModbusClientTcpFactory - TCP Client Creation

`ModbusClientTcpFactory` is a singleton factory for creating Modbus TCP clients in either master or slave role. The `createClient4Master` method opens an outbound TCP connection and routes all inbound Modbus responses to the supplied `ModbusResponseHandler`. The `createClient4Slave` method uses a `ModbusRequestHandler` instead, allowing the client to respond to requests from a remote TCP server acting as master.

```java
import com.github.zengfr.easymodbus4j.client.ModbusClient4TcpMaster;
import com.github.zengfr.easymodbus4j.client.ModbusClientTcpFactory;
import com.github.zengfr.easymodbus4j.handle.impl.ModbusMasterResponseHandler;
import com.github.zengfr.easymodbus4j.processor.ModbusMasterResponseProcessor;
import com.github.zengfr.easymodbus4j.ModbusConfs;

// --- Master role: client connects to a remote slave device ---
ModbusConfs.MASTER_SHOW_DEBUG_LOG = true;

ModbusMasterResponseProcessor processor = new MyMasterResponseProcessor((short) 0);
ModbusMasterResponseHandler responseHandler = new ModbusMasterResponseHandler(processor);

ModbusClient4TcpMaster client = 
    ModbusClientTcpFactory.getInstance().createClient4Master("192.168.1.10", 502, responseHandler);

// Wait for the async connection to establish before sending
Thread.sleep(3000);

// --- Slave role: client connects to a remote master server ---
// ModbusClient4TcpSlave slaveClient =
//     ModbusClientTcpFactory.getInstance().createClient4Slave("192.168.1.10", 502, requestHandler);
```
```

--------------------------------

### Create Modbus RTU Client (Slave Mode)

Source: https://github.com/zengfr/easymodbus4j/blob/master/README.md

Instantiate a Modbus RTU client acting as a slave. Requires a RequestHandler implementation.

```java
modbusClient = ModbusClientRtuFactory.getInstance().createClient4Slave(host,port, requestHandler);
```

--------------------------------

### Create Modbus TCP Server (Master Role)

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

Use ModbusServerTcpFactory to create a TCP server for the master role. This server listens for incoming slave connections and sends requests to them.

```java
import com.github.zengfr.easymodbus4j.server.ModbusServer4TcpMaster;
import com.github.zengfr.easymodbus4j.server.ModbusServerTcpFactory;
import com.github.zengfr.easymodbus4j.handle.impl.ModbusMasterResponseHandler;
import com.github.zengfr.easymodbus4j.handle.impl.ModbusSlaveRequestHandler;

// --- Master role: server accepts slave connections, then polls them ---
ModbusServer4TcpMaster server = 
    ModbusServerTcpFactory.getInstance().createServer4Master(502, responseHandler);

// --- Slave role: server accepts master connections and answers requests ---
// ModbusServerTcpFactory.getInstance().createServer4Slave(502, requestHandler);

Thread.sleep(3000); // wait for clients to connect
```

--------------------------------

### Maven Dependencies for easymodbus4j

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

Add these artifacts to your project's pom.xml to include easymodbus4j client, server, or extension modules.

```xml
<dependency>
    <groupId>com.github.zengfr</groupId>
    <artifactId>easymodbus4j-client</artifactId>
    <version>0.0.5</version>
</dependency>
<dependency>
    <groupId>com.github.zengfr</groupId>
    <artifactId>easymodbus4j-server</artifactId>
    <version>0.0.5</version>
</dependency>
<dependency>
    <groupId>com.github.zengfr</groupId>
    <artifactId>easymodbus4j-extension</artifactId>
    <version>0.0.5</version>
</dependency>
```

--------------------------------

### Add easymodbus4j Maven Dependency

Source: https://github.com/zengfr/easymodbus4j/wiki/QuickStart

Include this dependency in your project's pom.xml to use easymodbus4j.

```xml
<dependency>
<groupId>com.github.zengfr</groupId>
<artifactId>easymodbus4j</artifactId>
<version>0.0.3</version>
</dependency>
```

--------------------------------

### DeviceClient sendCommand API

Source: https://github.com/zengfr/easymodbus4j/blob/master/easymodbus4j-commandclient/src/main/resources/readme.txt

Use this API for sending general Modbus commands to a device. It requires the host, port, and a `DeviceCommand` object.

```java
DeviceClient.sendCommand(String host, int port, DeviceCommand<T> cmd);
```

--------------------------------

### Maven Dependencies for Easymodbus4j

Source: https://github.com/zengfr/easymodbus4j/blob/master/README.md

Include these dependencies in your Maven project to use the easymodbus4j client, server, and extension modules.

```xml
<dependency>
<groupId>com.github.zengfr</groupId>
<artifactId>easymodbus4j-client</artifactId>
<version>0.0.5</version>
</dependency>
<dependency>
<groupId>com.github.zengfr</groupId>
<artifactId>easymodbus4j-server</artifactId>
<version>0.0.5</version>
</dependency>
<dependency>
<groupId>com.github.zengfr</groupId>
<artifactId>easymodbus4j-extension</artifactId>
<version>0.0.5</version>
</dependency>
```

--------------------------------

### ModbusServerTcpFactory - TCP Server Creation

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

Details on creating Modbus TCP servers using ModbusServerTcpFactory. This factory supports both master and slave roles for the server, enabling it to listen for incoming connections and either send requests or respond to them.

```APIDOC
## ModbusServerTcpFactory - TCP Server Creation

`ModbusServerTcpFactory` creates listening Modbus TCP servers in either master or slave role. A server in master role listens for incoming slave connections and sends requests to them; a server in slave role listens for master connections and responds to their requests. Both modes are backed by Netty's NIO event loop for high concurrency.

```java
import com.github.zengfr.easymodbus4j.server.ModbusServer4TcpMaster;
import com.github.zengfr.easymodbus4j.server.ModbusServerTcpFactory;
import com.github.zengfr.easymodbus4j.handle.impl.ModbusMasterResponseHandler;
import com.github.zengfr.easymodbus4j.handle.impl.ModbusSlaveRequestHandler;

// --- Master role: server accepts slave connections, then polls them ---
ModbusServer4TcpMaster server = 
    ModbusServerTcpFactory.getInstance().createServer4Master(502, responseHandler);

// --- Slave role: server accepts master connections and answers requests ---
// ModbusServerTcpFactory.getInstance().createServer4Slave(502, requestHandler);

Thread.sleep(3000); // wait for clients to connect
```
```

--------------------------------

### Debug Modbus Frames with showFrameLog in Java

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

Use ModbusFrameUtil.showFrameLog to decode raw ModbusFrames into detailed logs. This includes hex wire bytes, parsed frame structure, and various decoded payload formats. Call this from any handler with access to the raw frame.

```java
import com.github.zengfr.easymodbus4j.util.ModbusFrameUtil;
import com.github.zengfr.easymodbus4j.protocol.ModbusFrame;
import io.netty.channel.Channel;
import io.netty.util.internal.logging.InternalLogger;
import io.netty.util.internal.logging.InternalLoggerFactory;

public class MyDebugResponseHandler {
    private static final InternalLogger logger = 
        InternalLoggerFactory.getInstance(MyDebugResponseHandler.class);

    public void onFrame(Channel channel, ModbusFrame frame) {
        // Emits a structured log block:
        // /192.168.1.10:502
        // ----------------------------------------------------------------
        // 00 01 00 00 00 06 01 03 00 00 00 0A          ← hex wire bytes
        // ModbusFrame{...}                              ← parsed structure
        // ----------------------------------------------------------------
        // hex    : 01 F4 00 64 ...
        // bitset : {0, 2, 8}
        // byte   : 1,-12,0,100,...
        // short  : 500,100,...
        // int    : 32768100,...
        // float b: 3.14,...
        // double b: 3.141592,...
        // ----------------------------------------------------------------
        ModbusFrameUtil.showFrameLog(logger, channel, frame);
    }
}
```

--------------------------------

### Show Modbus Frame Log in Java

Source: https://github.com/zengfr/easymodbus4j/blob/master/README.md

Utilize ModbusFrameUtil to display detailed logs for Modbus frames, including channel and frame information. This is helpful for debugging and monitoring Modbus communication.

```java
ModbusFrameUtil.showFrameLog(logger, channel, frame);
```

--------------------------------

### ModbusClientRtuFactory / ModbusServerRtuFactory

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

These factories provide methods to create RTU clients and servers for both master and slave roles. They mirror the TCP factories but handle Modbus RTU framing.

```APIDOC
## `ModbusClientRtuFactory` / `ModbusServerRtuFactory` — RTU Protocol

RTU factories mirror the TCP factories but wrap frames in Modbus RTU framing instead of Modbus TCP/IP framing. All four RTU deployment modes (server-master, server-slave, client-master, client-slave) are supported with identical handler/processor interfaces.

```java
import com.github.zengfr.easymodbus4j.client.ModbusClientRtuFactory;
import com.github.zengfr.easymodbus4j.server.ModbusServerRtuFactory;

// RTU client acting as master
ModbusClientRtuFactory.getInstance().createClient4Master("192.168.1.10", 502, responseHandler);

// RTU client acting as slave
ModbusClientRtuFactory.getInstance().createClient4Slave("192.168.1.10", 502, requestHandler);

// RTU server acting as master (waits for RTU slave devices to connect)
ModbusServerRtuFactory.getInstance().createServer4Master(502, responseHandler);

// RTU server acting as slave (responds to RTU master connections)
ModbusServerRtuFactory.getInstance().createServer4Slave(502, requestHandler);
```
```

--------------------------------

### DeviceClient.sendCommand

Source: https://github.com/zengfr/easymodbus4j/blob/master/easymodbus4j-commandclient/src/main/resources/readme.txt

Sends a generic command to a Modbus device. This is the primary method for sending commands.

```APIDOC
## DeviceClient.sendCommand

### Description
Sends a generic command to a Modbus device specified by host and port.

### Method Signature
`DeviceClient.sendCommand(String host, int port, DeviceCommand<T> cmd)`

### Parameters
- **host** (String) - The IP address or hostname of the Modbus device.
- **port** (int) - The port number of the Modbus device.
- **cmd** (DeviceCommand<T>) - The command object containing details about the operation.

### DeviceCommand Object Structure
```json
{
  "deviceId": "string",
  "ip": "string",
  "port": "integer",
  "version": "string",
  "functionCode": "integer",
  "address": "integer",
  "value": "T",
  "values": "T[]"
}
```

### DeviceCommand Parameters
- **deviceId** (String) - Required - The unique identifier for the device.
- **ip** (String) - Optional - The IP address of the device.
- **port** (int) - Optional - The port number of the device.
- **version** (String) - Optional - The version of the device.
- **functionCode** (int) - Required - The Modbus function code (e.g., 0x01, 0x03, 0x06, 0x10).
- **address** (int) - Required - The starting register address.
- **value** (T) - Optional - The value to write for single register operations.
- **values** (T[]) - Optional - The array of values to write for multiple register operations.
```

--------------------------------

### DeviceClient sendCommand2 API for Specific Function Codes

Source: https://github.com/zengfr/easymodbus4j/blob/master/easymodbus4j-commandclient/src/main/resources/readme.txt

This API is used for Modbus commands with specific function codes, such as writing multiple coils (0x0F) or writing multiple registers (0x10). It requires the host, port, and a `DeviceCommand` object.

```java
DeviceClient.sendCommand2(String host, int port, DeviceCommand<T> cmd);
```

--------------------------------

### Parse Command-Line Arguments for Modbus Configuration

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

Use `ModbusConfig.parse` to convert a string array of arguments into a typed configuration object. This method supports various Modbus connection types and parameters.

```java
import com.github.zengfr.easymodbus4j.example.ModbusConfig;
import com.github.zengfr.easymodbus4j.example.ModbusConsoleApp;

// Argument positions:
// [0] type            – 0=TCP server+client, 1=TCP server-master, 2=TCP client-slave,
//                       3=TCP client-master, 4=TCP server-slave,
//                       5=RTU server+client, 6=RTU server-master, 7=RTU client-slave,
//                       8=RTU client-master, 9=RTU server-slave
// [1] host            – remote IP (default: 127.0.0.1)
// [2] port            – TCP port (default: 502)
// [3] unitIdentifier  – Modbus unit ID (default: 1)
// [4] txIdOffset      – transaction identifier offset (default: 0)
// [5] showDebugLog    – true/false (default: true)
// [6] idleTimeOut     – seconds before idle disconnect (default: 30)
// [7] autoSend        – true/false, enable autoSend.txt scheduler (default: true)
// [8] sleep           – ms between scheduled sends (default: 15000)
// [9] heartbeat       – heartbeat string (default: "")
// [10] ignoreLengthThreshold – frame length threshold (default: 256)
// [11] udpPort        – UDP command port (default: 502)

String[] args = "3,192.168.1.100,502,1,0,true,60,true,5000".split("[,;|]");
ModbusConfig cfg = ModbusConfig.parse(args);
// cfg.type=3 → TCP client-master
// cfg.host="192.168.1.100", cfg.port=502, cfg.sleep=5000 ms

ModbusConsoleApp.start(cfg);
```

--------------------------------

### Implement ModbusMasterResponseProcessor for Master Responses

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

Extend AbstractModbusProcessor and implement ModbusMasterResponseProcessor to handle inbound Modbus responses. The processResponseFrame method allows correlation between requests and responses.

```java
import com.github.zengfr.easymodbus4j.func.AbstractRequest;
import com.github.zengfr.easymodbus4j.func.request.ReadCoilsRequest;
import com.github.zengfr.easymodbus4j.func.request.ReadDiscreteInputsRequest;
import com.github.zengfr.easymodbus4j.func.response.ReadCoilsResponse;
import com.github.zengfr.easymodbus4j.func.response.ReadDiscreteInputsResponse;
import com.github.zengfr.easymodbus4j.processor.AbstractModbusProcessor;
import com.github.zengfr.easymodbus4j.processor.ModbusMasterResponseProcessor;
import com.github.zengfr.easymodbus4j.protocol.ModbusFunction;
import com.github.zengfr.easymodbus4j.util.ModbusFunctionUtil;
import io.netty.channel.Channel;

public class MyMasterResponseProcessor extends AbstractModbusProcessor
        implements ModbusMasterResponseProcessor {

    public MyMasterResponseProcessor(short transactionIdentifierOffset) {
        super(transactionIdentifierOffset, true);
    }

    @Override
    public boolean processResponseFrame(Channel channel, int unitId,
                                        AbstractRequest reqFunc, ModbusFunction respFunc) {
        boolean success = this.isRequestResponseMatch(reqFunc, respFunc);

        if (respFunc instanceof ReadCoilsResponse && reqFunc instanceof ReadCoilsRequest) {
            ReadCoilsResponse resp = (ReadCoilsResponse) respFunc;
            ReadCoilsRequest req  = (ReadCoilsRequest)  reqFunc;
            // e.g. resp.getCoilStatus().get(0) → boolean value of first coil
            success = true;
        }

        if (respFunc instanceof ReadDiscreteInputsResponse) {
            ReadDiscreteInputsResponse resp = (ReadDiscreteInputsResponse) respFunc;
            byte[] raw        = resp.getInputStatus().toByteArray();
            byte[] values     = ModbusFunctionUtil.getFunctionValues(respFunc);
            // convert to int[], short[], float[], etc. via ByteUtil helpers
            success = true;
        }
        return success;
    }
}
```

--------------------------------

### DeviceCommand Class Structure

Source: https://github.com/zengfr/easymodbus4j/blob/master/easymodbus4j-commandclient/src/main/resources/readme.txt

The `DeviceCommand` class is a generic class used to encapsulate Modbus command details, including device identification, connection parameters, function code, and data values.

```java
public class DeviceCommand<T> {
	/** 设备标识id(必选) */
	public String deviceId;
	/** 设备ip(可选) */
	public String ip;
	/** 设备port(可选) */
	public int port;
	/** 设备型号(可选) */
	public String version;
	/** 见class FunctionCode */
	public int functionCode;
	/** 寄存器地址 */
	public int address;
	/** 寄存器地址值 */
	public T value;
	/** 寄存器地址值 */
	public T[] values;
}
```

--------------------------------

### Create RTU Modbus Client/Server Factories

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

Use RTU factories to create Modbus clients and servers that communicate using the RTU framing protocol. Supported modes include client-master, client-slave, server-master, and server-slave.

```java
import com.github.zengfr.easymodbus4j.client.ModbusClientRtuFactory;
import com.github.zengfr.easymodbus4j.server.ModbusServerRtuFactory;

// RTU client acting as master
ModbusClientRtuFactory.getInstance().createClient4Master("192.168.1.10", 502, responseHandler);

// RTU client acting as slave
ModbusClientRtuFactory.getInstance().createClient4Slave("192.168.1.10", 502, requestHandler);

// RTU server acting as master (waits for RTU slave devices to connect)
ModbusServerRtuFactory.getInstance().createServer4Master(502, responseHandler);

// RTU server acting as slave (responds to RTU master connections)
ModbusServerRtuFactory.getInstance().createServer4Slave(502, requestHandler);
```

--------------------------------

### DeviceClient.sendCommand2

Source: https://github.com/zengfr/easymodbus4j/blob/master/easymodbus4j-commandclient/src/main/resources/readme.txt

Sends a command to a Modbus device, specifically designed for function codes like WRITE_MULTIPLE_COILS and WRITE_MULTIPLE_REGISTERS.

```APIDOC
## DeviceClient.sendCommand2

### Description
Sends a command to a Modbus device, optimized for specific write operations like writing multiple coils or registers.

### Method Signature
`DeviceClient.sendCommand2(String host, int port, DeviceCommand<T> cmd)`

### Parameters
- **host** (String) - The IP address or hostname of the Modbus device.
- **port** (int) - The port number of the Modbus device.
- **cmd** (DeviceCommand<T>) - The command object containing details about the operation.

### DeviceCommand Object Structure
```json
{
  "deviceId": "string",
  "ip": "string",
  "port": "integer",
  "version": "string",
  "functionCode": "integer",
  "address": "integer",
  "value": "T",
  "values": "T[]"
}
```

### DeviceCommand Parameters
- **deviceId** (String) - Required - The unique identifier for the device.
- **ip** (String) - Optional - The IP address of the device.
- **port** (int) - Optional - The port number of the device.
- **version** (String) - Optional - The version of the device.
- **functionCode** (int) - Required - The Modbus function code. This method is particularly suited for `WRITE_MULTIPLE_COILS` (0x0F) and `WRITE_MULTIPLE_REGISTERS` (0x10).
- **address** (int) - Required - The starting register address.
- **value** (T) - Optional - The value to write for single register operations.
- **values** (T[]) - Optional - The array of values to write for multiple register operations.
```

--------------------------------

### Process Modbus Request/Response in Java

Source: https://github.com/zengfr/easymodbus4j/blob/master/README.md

Implement this method to handle incoming Modbus requests and their corresponding responses. It allows for custom business logic based on the request and response types, such as ReadCoilsResponse.

```java
public void processResponseFrame(Channel channel, int unitId, AbstractFunction reqFunc, ModbusFunction respFunc) {
			if (respFunc instanceof ReadCoilsResponse) {
				ReadCoilsResponse resp = (ReadCoilsResponse) respFunc;
				ReadCoilsRequest req = (ReadCoilsRequest) reqFunc;
				//process business logic for req/resp
			}
	};
```

--------------------------------

### Send Modbus Request with Easymodbus4j

Source: https://github.com/zengfr/easymodbus4j/blob/master/README.md

Use this code to send various Modbus requests like reading coils, discrete inputs, or writing registers. Ensure a delay after connection establishment for asynchronous operations.

```java
Thread.sleep(3*1000);// sleep 3s before,when client or server open connection is async;
Channel  channel =  client.getChannel());
Channel  channel =  server.getChannelsBy(...)); 
ChannelSender sender = ChannelSenderFactory.getInstance().get(channel);
ChannelSender sender2 = new ChannelSender(channel,unitId,protocolIdentifier);
sender.readCoils(...)
sender.readDiscreteInputs(...)
sender.writeSingleRegister(...)
```

--------------------------------

### Implement Modbus Slave Request Processor in Java

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

Implement ModbusSlaveRequestProcessor to handle various Modbus function codes. Each method receives unit ID and request, returning the appropriate response. The framework manages serialization and transmission.

```java
import com.github.zengfr.easymodbus4j.func.request.*;
import com.github.zengfr.easymodbus4j.func.response.*;
import com.github.zengfr.easymodbus4j.processor.AbstractModbusProcessor;
import com.github.zengfr.easymodbus4j.processor.ModbusSlaveRequestProcessor;
import com.github.zengfr.easymodbus4j.common.util.BitSetUtil;
import com.github.zengfr.easymodbus4j.common.util.RegistersUtil;
import java.util.BitSet;
import java.util.Random;

public class MySlaveRequestProcessor extends AbstractModbusProcessor
        implements ModbusSlaveRequestProcessor {

    private final Random random = new Random();

    public MySlaveRequestProcessor(short transactionIdentifierOffset) {
        super(transactionIdentifierOffset, true);
    }

    @Override
    public ReadCoilsResponse readCoils(short unitId, ReadCoilsRequest req) {
        BitSet coils = BitSetUtil.getRandomBits(req.getQuantityOfCoils(), random);
        return new ReadCoilsResponse(coils);
    }

    @Override
    public ReadHoldingRegistersResponse readHoldingRegisters(short unitId, ReadHoldingRegistersRequest req) {
        int[] regs = RegistersUtil.getRandomRegisters(req.getQuantityOfInputRegisters(), 0, 65535, random);
        return new ReadHoldingRegistersResponse(regs);
    }

    @Override
    public WriteSingleRegisterResponse writeSingleRegister(short unitId, WriteSingleRegisterRequest req) {
        // persist req.getRegisterValue() at req.getRegisterAddress() if needed
        return new WriteSingleRegisterResponse(req.getRegisterAddress(), req.getRegisterValue());
    }

    @Override
    public WriteMultipleRegistersResponse writeMultipleRegisters(short unitId, WriteMultipleRegistersRequest req) {
        return new WriteMultipleRegistersResponse(req.getStartingAddress(), req.getQuantityOfRegisters());
    }

    @Override
    public ReadDiscreteInputsResponse readDiscreteInputs(short unitId, ReadDiscreteInputsRequest req) {
        BitSet bits = BitSetUtil.getRandomBits(req.getQuantityOfCoils(), random);
        return new ReadDiscreteInputsResponse(bits);
    }

    @Override
    public ReadInputRegistersResponse readInputRegisters(short unitId, ReadInputRegistersRequest req) {
        int[] regs = RegistersUtil.getRandomRegisters(req.getQuantityOfInputRegisters(), 1, 1024, random);
        return new ReadInputRegistersResponse(regs);
    }

    @Override
    public WriteSingleCoilResponse writeSingleCoil(short unitId, WriteSingleCoilRequest req) {
        return new WriteSingleCoilResponse(req.getOutputAddress(), req.isState());
    }

    @Override
    public WriteMultipleCoilsResponse writeMultipleCoils(short unitId, WriteMultipleCoilsRequest req) {
        return new WriteMultipleCoilsResponse(req.getStartingAddress(), req.getQuantityOfOutputs());
    }
}
```

--------------------------------

### ChannelSender — Sending Modbus Requests

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

The ChannelSender API is used to send all supported Modbus function codes. It can be obtained from ChannelSenderFactory or constructed directly with a unit identifier. Methods are available in both synchronous and asynchronous variants.

```APIDOC
## `ChannelSender` — Sending Modbus Requests

`ChannelSender` is the main API for sending all supported Modbus function codes. Obtain an instance from `ChannelSenderFactory` using an active Netty `Channel`, or construct one directly with an explicit unit identifier. All methods have both synchronous and asynchronous (`Async`) variants.

```java
import com.github.zengfr.easymodbus4j.sender.ChannelSender;
import com.github.zengfr.easymodbus4j.sender.ChannelSenderFactory;
import io.netty.channel.Channel;

Channel channel = client.getChannel(); // or server.getChannelsBy(...)
if (channel != null && channel.isActive() && channel.isWritable()) {

    ChannelSender sender = ChannelSenderFactory.getInstance().get(channel);
    // Custom unit identifier variant:
    // ChannelSender sender = new ChannelSender(channel, (short) 1);

    // FC1 – Read Coils (async)
    sender.readCoilsAsync(/*startAddress*/ 0, /*quantity*/ 8);

    // FC2 – Read Discrete Inputs (sync)
    sender.readDiscreteInputs(/*startAddress*/ 65, /*quantity*/ 16);

    // FC3 – Read Holding Registers (async)
    sender.readHoldingRegistersAsync(/*startAddress*/ 33, /*quantity*/ 17);

    // FC4 – Read Input Registers (sync)
    sender.readInputRegisters(/*startAddress*/ 49, /*quantity*/ 18);

    // FC5 – Write Single Coil
    sender.writeSingleCoil(/*outputAddress*/ 17, /*state*/ false);

    // FC6 – Write Single Register
    sender.writeSingleRegister(/*registerAddress*/ 18, /*value*/ 22);

    // FC15 – Write Multiple Coils
    sender.writeMultipleCoils(/*startAddress*/ 25, new boolean[]{true, false, true, false, true, true});

    // FC16 – Write Multiple Registers
    sender.writeMultipleRegisters(/*startAddress*/ 24, new int[]{1, 3, 5, 7, 14});
}
```
```

--------------------------------

### Send Modbus Requests with ChannelSender

Source: https://context7.com/zengfr/easymodbus4j/llms.txt

Utilize the ChannelSender API to send various Modbus function code requests. Obtain a sender instance from ChannelSenderFactory using an active Netty Channel or construct one with an explicit unit identifier. Both synchronous and asynchronous variants are available.

```java
import com.github.zengfr.easymodbus4j.sender.ChannelSender;
import com.github.zengfr.easymodbus4j.sender.ChannelSenderFactory;
import io.netty.channel.Channel;

Channel channel = client.getChannel(); // or server.getChannelsBy(...)
if (channel != null && channel.isActive() && channel.isWritable()) {

    ChannelSender sender = ChannelSenderFactory.getInstance().get(channel);
    // Custom unit identifier variant:
    // ChannelSender sender = new ChannelSender(channel, (short) 1);

    // FC1 – Read Coils (async)
    sender.readCoilsAsync(/*startAddress*/ 0, /*quantity*/ 8);

    // FC2 – Read Discrete Inputs (sync)
    sender.readDiscreteInputs(/*startAddress*/ 65, /*quantity*/ 16);

    // FC3 – Read Holding Registers (async)
    sender.readHoldingRegistersAsync(/*startAddress*/ 33, /*quantity*/ 17);

    // FC4 – Read Input Registers (sync)
    sender.readInputRegisters(/*startAddress*/ 49, /*quantity*/ 18);

    // FC5 – Write Single Coil
    sender.writeSingleCoil(/*outputAddress*/ 17, /*state*/ false);

    // FC6 – Write Single Register
    sender.writeSingleRegister(/*registerAddress*/ 18, /*value*/ 22);

    // FC15 – Write Multiple Coils
    sender.writeMultipleCoils(/*startAddress*/ 25, new boolean[]{true, false, true, false, true, true});

    // FC16 – Write Multiple Registers
    sender.writeMultipleRegisters(/*startAddress*/ 24, new int[]{1, 3, 5, 7, 14});
}
```

--------------------------------

### Modbus Function Codes

Source: https://github.com/zengfr/easymodbus4j/blob/master/easymodbus4j-commandclient/src/main/resources/readme.txt

Defines common Modbus function codes used in commands, such as WRITE_MULTIPLE_COILS and WRITE_MULTIPLE_REGISTERS.

```java
WRITE_MULTIPLE_COILS = 0x0F;
WRITE_MULTIPLE_REGISTERS = 0x10;
```
Tokens:
Raw