Using the Modbus protocol in Android

Introduction

This technical note aims to explain how to use the Modbus protocol in Android. The first section describes the main functions of the protocol: the purpose of its use, the structure of the packages and the architectural context in which the protocol is typically implemented. The part of the technical note is focused on the description of the different options through which to use Modbus in Android.

Modbus protocol

Modbus is an application layer messaging protocol for communication between devices based on the client/server paradigm. It is used in the field of automation and allows devices to exchange messages. Modbus is typically used to transmit signals from instrumentation and control devices to a main controller or a data gathering. The specifications for the latest version of the protocol, 1.1b3, are available in the official Modbus Organization website.

The following figure shows the client/server structure of Modbus, where the client acts as the Master and the server is the Slave. Communication is based on transactions, which consist of a request issued by the client to the server and a response issued by the server to the client.

The communication is based on a simple Protocol Data Unit (PDU) defined by Modbus, which is independent of the underlying communication layers. The PDU is composed by a function code and the data. The mapping of Modbus on specific buses or network can introduce some additional fields on the Application Data Unit (ADU), as you can see in the following figure.

The protocol specification defines three types of PDU's:

1. Request PDU: a code specifying a function (Function Code, 1 byte) and function specific data (Function Data, varying number of bytes)
2. Response PDU: the function code corresponding to the request (Function Code, 1 byte) and response specific data (Response Data, varying number of bytes)
3. Exception Response PDU: the function code corresponding to the request + 0x80 (128), (Error Code, 1 byte) and a code specifying the exception (Exception Code, 1 byte)

There are two versions of Modbus protocol:

1. Modbus RTU and Modbus ASCII for serial lines communication
2. Modbus TCP for Ethernet communication

Information is stored in the Slave device in four different tables: two for coils and two for registers. Each table has 9999 possible addresses. Coils are discrete values (1 bit each) and registers are numerical values (each 1 word = 16 bits = 2 bytes). The following table contains the basic Modbus data types defined by the specification.

Coil/Register Numbers	Data Addresses	Type	Table Name
1-9999	0000 to 270E	Read-Write	Discrete Output Coils
10001-19999	0000 to 270E	Read-Only	Discrete Input Contacts
30001-39999	0000 to 270E	Read-Only	Analog Input Registers
40001-49999	0000 to 270E	Read-Write	Analog Output Holding Registers

Modbus RTU

Modbus RTU (Remote Terminal Unit) is used to connect a supervisory computer with a RTU in supervisor control and data acquisition systems.

This packet is composed by four parts:

1. Slave ID: the unique address from 1 to 247 (maximum number of Slaves for each master)
2. Function Code: the table to access and whether to read or write
3. Data
4. Error check: typically CRC (Cyclic Redundancy Check) is used

Modbus TCP/IP

TCP is a connection-based protocol so a connection must be established before transferring data.

Modbus TCP simply takes a Modbus RTU message, transmits it with a TCP/IP wrapper and sends it over network instead of serial lines.

The packet is composed by six parts:

1. Transition ID: 2 bytes set by the client to uniquely identify each request
2. Protocol ID: 2 bytes set by the client, always 0000
3. Length: 2 bytes for number of bytes in the message to follow
4. Unit ID: 1 byte set by the client and echoed by the server
5. Function Code: the table to access and whether to read or write
6. Data

Modbus libraries for Android

The are several Java libraries that implement the Modbus protocol, the most used are:

1. jamod
2. jLibModbus
3. j2mod
4. Modbus4j

Let's have a look at the first two.

jamod

jamod (Java Modbus Library) is a pure Java library that can be used to implement Modbus Master and Slave both in IP and serial transport flavours. The library is well documented as it provides both complete API documentation and guidelines on how to use jamod.

The Master is the client, which establishes a connection with the Slave (i.e. the server) and uses this connection for sending a Request to the Slave, from which a Response will be received. There can be only one Master requiring data from a source (data acquisition) or writing data to a sink (device control). The relevant Java classes to implement a Master are:

• SerialConnection for the creation of a serial connection
• ModbusSerialTransaction for the transaction which is composed by Request and Response
• SerialParameters the parameters to be used

The Slave is a server which has a listener for receiving an incoming request from the Master which are served providing a corresponding response. The relevant Java classes to implement a Slave are:

• ModbusSerialListener the listener for a request from a Master
• DigitalIn, DigitalOut, InputRegister, Register the Modbus data types
• SerialParameters the parameters to be used

j2mod is a fork of the jamod 1.2 codebase and has numerous bug fixes and additional features with respect to the original project. This is likely the best choice for jamod users looking to migrate to an up-to-date library.

PROS

1. Easy to use
2. Fully documented
3. Several usage examples available

CONS

1. Modbus RTU relies on Java Communications API, which has no official implementation for Android. The only option is to use some port of RXTX for Android
2. The library is not up-to-date, the lastest official release (1.2rc1) dates back to 2004

jLibModbus

jLibModbus is an implementation of the Modbus protocol in Java language. It supports the most common libraries for serial communication such as RXTX, jssc, jSerialComm, purejavacomm and Java Communications API. jLibModbus covers all the main features of the Modbus protocol, such as Modbus RTU, Modbus TCP, Modbus ASCII, Modbus Master and Modbus Slave.

jLibModbus source code is hosted in this github repository.

PROS

1. Actively maintained
2. Support for several different serial communication libraries (jssc, RXTX, purejavacomm, Java Communications API)
3. (Quite) complete implementation of the Modbus protocol.

CONS

1. Code structure needs some time to be understood
2. Documentation sometimes unclear or lacking

Serial libraries for Modbus RTU in Android

An aspect which requires particular attention when using Modbus RTU on Android is the choice of the serial communication library for two reason:

1. Java libraries, especially when Java Communications API are involved, try to abstract away how the serial device is accessed by the platform, thus requiring the use of an external library for serial communication
2. implementations for Linux of Java serial libraries might not be easy to port to Android because of differences between the two platforms, especially regarding the compilation of the native code accessing serial port devices

Libraries like RXTX for example have ports for Android, but are generally unmaintained and not compatible with recent Android version.

jSerialComm

jSerialComm is a library written in Java which provides a way to access standard serial ports without requiring external libraries or native code. The declared purpose of the library is to be a valid alternative to RXTX and Java Communications API. jSerialComm is platform-independent (automatically uses correct native library based on current architecture) and has the ability to open multiple ports simultaneously.

See the Javadoc Library Reference for a complete overview of jSerialComm API.

PROS

1. Multi-platform (in particular supports Android)
2. Lightweight and efficient
3. Regularly updated

CONS

1. Cannot be used straight away in combination with jamod, as it's not a Java Communications API implementation