Nifty Modbus is a delightful little Modbus library for Java. It aims to be easy to use, reliable, and cover the most common Modbus use cases. It also is designed around some core APIs that make it easy to extend.

Nifty Modbus is built on top of the Netty asynchronous network library.

Here is an example of using the Nifty Modbus TCP client to read some Modbus registers:

// create the TCP client
NettyTcpModbusClientConfig config = new NettyTcpModbusClientConfig(hostName, hostPort);
config.setAutoReconnect(false);
ModbusClient client = new TcpNettyModbusClient(config);
try {
	// connect the client
	client.start().get();

	// request holding registers
	ModbusMessage req = readHoldingsRequest(unitId, addr, count);
	RegistersModbusMessage res = client.send(req).unwrap(RegistersModbusMessage.class);

	// print out the results
	short[] data = res.dataDecode();
	for ( int i = 0, len = data.length; i < len; i   ) {
		System.out.printf("%d: 0xX\n", addr   i, data[i]);
	}
} finally {
	client.stop();
}

The above snippet was taken from the TcpClientReadRegistersExample class. See the examples project project for more samples.

The shell component provides a basic interactive command-line application for reading from and writing to Modbus devices. It supports both RTU and TCP connections.

The tcp component provides a basic Modbus server in addition to a Modbus client, in the NettyTcpModbusServer class. This server will listen for Modbus requests and pass them over to a consumer of your own making. That consumer can also provide any necessary Modbus response to send back to the connected client.

Here is an example of using the Nifty Modbus TCP server to respond to read holding register requests:

NettyTcpModbusServer server = new NettyTcpModbusServer(bindPort);
server.setMessageHandler((msg, sender) -> {
	// this handler only supports read holding registers requests
	RegistersModbusMessage req = msg.unwrap(RegistersModbusMessage.class);
	if ( req != null && req.getFunction().blockType() == ModbusBlockType.Holding ) {

		// generate some fake data that matches the request register count
		short[] resultData = new short[req.getCount()];
		for ( int i = 0; i < resultData.length; i   ) {
			resultData[i] = (short) i;
		}

		// respond with the fake data
		sender.accept(readHoldingsResponse(req.getUnitId(), req.getAddress(), resultData));
	} else {
		// send back error that we don't handle that request
		sender.accept(new BaseModbusMessage(msg.getUnitId(), msg.getFunction(),
				ModbusErrorCode.IllegalFunction));
	}
});

try {
	server.start();
	while ( true ) {
		Thread.sleep(60_000);
	}
} finally {
	server.stop();
}

The above snippet was taken from the TcpServerExample class.

Nifty Modbus requires a Java 8 or later runtime and has core dependencies on Netty 4.1 and slf4j 1.7. For Modbus RTU (serial port) the rtu-jsc component depends on jSerialComm 2.9. More specifically, it requires the following direct dependencies:

The rtu-pjc component is an alternative RTU implementation that relies on the PureJavaComm serial library, and can be used instead of the jSerialComm component. That requires the following dependencies:

Nifty Modbus can be integrated into your project using the following coordinates, all of which use the net.solarnetwork.common Group identifier:

Usually it is sufficient to declare just the RTU and/or TCP components in your project, and the others will be pulled in automatically. For example to include both RTU using jSerialComm and TCP support in a Gradle project:

dependencies {
	implementation "net.solarnetwork.common:nifty-modbus-rtu-jsc:1.0.0"
	implementation "net.solarnetwork.common:nifty-modbus-tcp:1.0.0"
}

To build Nifty Modbus yourself, clone or download this repository. Then:

# Linux/macOS/etc
./gradlew build -x test

# Or Windows
.\gradlew.bat build -x test

The component artifacts will be created within the build/libs directory of each component:

• api/build/libs/nifty-modbus-api-X.Y.Z.jar
• core/build/libs/nifty-modbus-core-X.Y.Z.jar
• rtu/build/libs/nifty-modbus-rtu-X.Y.Z.jar
• rtu-jsc/build/libs/nifty-modbus-rtu-jsc-X.Y.Z.jar
• rtu-pjc/build/libs/nifty-modbus-rtu-pjc-X.Y.Z.jar
• tcp/build/libs/nifty-modbus-tcp-X.Y.Z.jar

Having a well-tested and reliable Modbus library is a core goal of this project. Unit tests are executed automatically after every push into this repository and their associated code coverage is uploaded to Codecov.