B4A Library Modbus Master / Client (PLCs) - TCP Library

Hello everyone,
Here is a Modbus library that I just wrapped to test some industrial Modbus TCP valves, so I thought that I would share it with the community. Using this library, you can connect your B4A apps directly to industrial devices (PLCs) over TCP to read and write Modbus data. Your app should (in theory) connect to any Modbud Server (Slave) devices running over Ethernet or WiFi.

B4A library tab (Network, not really needed)

Important:
There are 4 separate files in the attached library zip file, place all 4 files in your B4A additional libraries folder.

Updated - B4A Modbus Master test app:

SS_ModbusMaster

Author: Peter Simpson
Version: 1.01

• ModbusMasterTCP
  • Events:
    • CoilRead (Success As Boolean, Data() As Boolean, Message As String)
    • ConnectionCheckDone (IsLive As Boolean, Message As String)
    • DiagnosticRequest (SubFunction As Int, Data As Int)
    • DiscreteInputRead (Success As Boolean, Data() As Boolean, Message As String)
    • HoldingRegisterRead (Success As Boolean, Data() As Short, Message As String)
    • InitResult (Success As Boolean, Message As String)
    • InputRegisterRead (Success As Boolean, Data() As Short, Message As String)
    • TestCompleted (Success As Boolean, Message As String)
    • WriteResult (Success As Boolean, Message As String)
  • Fields:
    • TEST_COIL As Int
    • TEST_DISCRETE As Int
    • TEST_HOLDING As Int
    • TEST_INPUT As Int
    • TEST_NONE As Int
      Constants to control the initial connection test behavior.
  • Functions:
    • DiagnosticRequest (SubFunction As Int, Data As Int) As Int
      Performs Modbus Function Code 8 (Diagnostics).
      Supports Subfunction 0 (Return Query Data / Loopback) — echoes the integer data.
      Raises the DiagnosticRequest event so B4A/B4J can receive the response.
      SubFunction: The diagnostics subfunction code (only 0 supported).
      Data: The integer data to echo back.
    • Disconnect
      Disconnects and closes the underlying Modbus TCP connection.
      After calling this, the connection must be re-initialised with Initialize() before further requests.
    • Initialize (EventName As String, Host As String, Port As Int, Encapsulated As Boolean, KeepAlive As Boolean, Timeout As Int, Retries As Int, TestFunction As Int, TestAddress As Int)
      Initializes the Modbus TCP connection parameters and attempts to configure the library.
      This function is asynchronous and raises the InitResult event upon completion.
      EventName: The prefix used for the callback events (e.g., "MB" will raise MB_InitResult).
      Host: The IP address or hostname of the Modbus TCP slave device (or TCP/RTU gateway).
      Port: The TCP port of the Modbus device (usually 502).
      Encapsulated: If true, uses Modbus RTU over TCP (Encapsulated). False for standard Modbus TCP.
      KeepAlive: If true, the TCP socket connection is kept alive between requests.
      Timeout: The connection and request timeout in milliseconds.
      Retries: The number of retries the library will perform for failed requests.
      TestFunction: The memory area to use for the connection heartbeat test. Use one of TEST_* constants (0–4).
      TestAddress: The address to read during the heartbeat test (ignored if TestFunction is TEST_NONE).
    • IsInitialized As Boolean
      Returns whether the Modbus connection is currently ready to process requests.
    • ReadCoil (Start As Int, Len As Int)
      Reads a contiguous block of Coil Statuses (Function Code 1).
      The result is returned asynchronously in the CoilRead event.
      Start: The starting address of the first coil to read (0-based).
      Len: The number of coils to read.
    • ReadDiscreteInput (Start As Int, Len As Int)
      Reads a contiguous block of Discrete Inputs (Function Code 2).
      The result is returned asynchronously in the DiscreteInputRead event.
      Start: The starting address of the first discrete input to read (0-based).
      Len: The number of discrete inputs to read.
    • ReadHoldingRegisters (Start As Int, Len As Int)
      Reads a contiguous block of Holding Registers (Function Code 3).
      The result is returned asynchronously in the HoldingRegisterRead event.
      Data is returned as an array of Short (16-bit signed integers).
      Start: The starting address of the first register to read (0-based).
      Len: The number of registers to read.
    • ReadInputRegisters (Start As Int, Len As Int)
      Reads a contiguous block of Input Registers (Function Code 4).
      The result is returned asynchronously in the InputRegisterRead event.
      Data is returned as an array of Short (16-bit signed integers).
      Start: The starting address of the first register to read (0-based).
      Len: The number of registers to read.
    • ReadWriteMultipleRegisters (ReadStart As Int, ReadLen As Int, WriteStart As Int, WriteValues As Short())
      Function Code 23: Read/Write Multiple Registers (implemented as FC16 followed by FC3).
      Reads a block of holding registers while writing another block in a chained two-step sequence.
      On success, results are raised via HoldingRegisterRead; write results and errors via WriteResult.
      ReadStart: The starting address of the registers to read (0-based).
      ReadLen: The number of registers to read.
      WriteStart: The starting address of the registers to write (0-based).
      WriteValues: The array of values to write starting at WriteStart.
    • TestFunction
      Executes a full self-test sequence based on the underlying Modbus connection state.
      The result is returned asynchronously in the TestCompleted event.
      Should be called after a successful Initialize().
    • WriteCoil (Offset As Int, Value As Boolean)
      Writes a single Coil value (Function Code 5).
      The result is returned asynchronously in the WriteResult event.
      Offset: The address of the coil to write to (0-based).
      Value: The boolean value (True/False) to write to the coil.
    • WriteCoils (Start As Int, Values As Boolean())
      Writes multiple Coil values (Function Code 15).
      The result is returned asynchronously in the WriteResult event.
      Start: The starting address of the first coil to write (0-based).
      Values: An array of boolean values written sequentially starting from Start.
    • WriteRegister (Offset As Int, Value As Int)
      Writes a single Holding Register value (Function Code 6).
      The result is returned asynchronously in the WriteResult event.
      Offset: The address of the register to write to (0-based).
      Value: The 16-bit integer value (Short-compatible) to write to the register.
    • WriteRegisters (Start As Int, Values As Short())
      Writes multiple Holding Register values (Function Code 16).
      The result is returned asynchronously in the WriteResult event.
      Start: The starting address of the first register to write (0-based).
      Values: An array of 16-bit integer values written sequentially starting from Start.
  • Properties:
    • HostAddress As String [read only]
      Returns the host address configured during Initialize().
    • SlaveID As Int
      Property: Gets and Sets the Modbus Slave Unit ID (1–247).
      This value is used for all subsequent requests while the connection is active.

B4A Modbus Master quick reference (FC → Method)​

FC (Hex)	FC (Dec)	Description	Data Type	R/W Operation	Method Name	Event Raised
0x01	FC1	Read Coils	Coil (Discrete Output)	Read (R)	ReadCoil(Start, Len)	_coilread
0x02	FC2	Read Discrete Inputs	Discrete Input	Read (R)	ReadDiscreteInput(Start, Len)	_discreteinputread
0x03	FC3	Read Holding Registers	Holding Register	Read (R)	ReadHoldingRegisters(Start, Len)	_holdingregisterread
0x04	FC4	Read Input Registers	Input Register	Read (R)	ReadInputRegisters(Start, Len)	_inputregisterread
0x05	FC5	Write Single Coil	Coil (Discrete Output)	Write (W)	WriteCoil(Offset, Value)	_writeresult
0x06	FC6	Write Single Register	Holding Register	Write (W)	WriteRegister(Offset, Value)	_writeresult
0x08	FC8	Diagnostic (Loopback)	N/A	Diagnostic	DiagnosticRequest(SubFunction, Data)	_diagnosticrequest
0x0F	FC15	Write Multiple Coils	Coil (Discrete Output)	Write (W)	WriteCoils(Start, Values)	_writeresult
0x10	FC16	Write Multiple Registers	Holding Register	Write (W)	WriteRegisters(Start, Values)	_writeresult
0x17	FC23	Read/Write Multiple Registers. Implemented as Chained FC16 + FC3	Holding Register	Read/Write (R/W)	ReadWriteMultipleRegisters (ReadStart, ReadLen, WriteStart, WriteValues)	_holdingregisterread and _writeresult

PLEASE TAKE NOTE:

1. The _Initialize function was updated adding TestFunction & TestAddress to the end of the signature
2. Renamed the library from ModbusMaster to ModbusMasterTCP for continuity with the Slave library
3. Removed SLAVE_ID = x (No longer needed)
4. Removed ALL references of 'SlaveId As Int' from all of the Read and Write signatures. If need be, you can now set or switch the SlaveID at will by using ModBus.SlaveID = x (x being the ID number).

Update: V1.01

• Cleaned up the JavaDoc comments
• Updated all _write events to show wrote values
• Added TestCompleted Event
• Added DiagnosticRequest Event
• Added InputRegisterRead Event
• Added DiscreteInputRead Event
• Added Modbus Function 8 (Loopback)
• Added Modbus Function 15
• Added Modbus Function 23 (FC16 + FC3 chained)
• Added TestFunction Function
• Added WriteCoils Function
• Added ReadWriteMultipleRegisters Function
• Added TEST_NONE Field
• Added TEST_COIL Field
• Added TEST_DISCRETE Field
• Added TEST_HOLDING Field
• Added TEST_INPUT Field
• Added isModbusReady Field
• Updated the test app (attached)

Plus a few other improvements.

D = 61+64


Enjoy...

 

[SimonAndroid]

Sorry for my curiosity, but was this library converted for B4A from Python or another language? I needed this a few months ago and created some procedures in Python, where the library works very well. Best regards.

 

[Peter Simpson]

Hello @SimonAndroid.

but was this library converted for B4A from Python or another language?

No, not at all, it's a straightforward Java library wrap. Once I got my head around the six basic FCs, I then added the other Function Code features. It only took a few hours to wrap the original java library which I fully tested with a Windows slave simulator, extending and testing this library took another day.

Below is a link that some developers might find useful.

Modbus CRC-16 checksum function with detailed breakdown for each hex value:

✅ Modbus CRC-16 / CRC16 checksum function

SubName: Modbus CRC-16 is used to ensure data integrity in Modbus RTU (Remote Terminal Unit) communications. Description: This function takes a command message Bytes and performs the necessary bitwise operations to generate a 16-bit CRC checksum, and outputs the checksum value as a hexadecimal...

www.b4x.com

Enjoy...

 

[Peter Simpson]

Hello Everyone,
I've updated the library to V1.01. Please read carefully the PLEASE TAKE NOTE: section at the bottom of post #1 as the Initialize signature has changed and so has the library name.

Enjoy...

XUI (B4A/B4J) - Future cross-platform libraries:
I’ll be releasing a Modbus TCP Server (Slave) library that simulates Modbus hardware. I’ll also be releasing a second Modbus TCP Client (Master) library for reading and writing to and from Modbus hardware. This library uses FC23 without chaining.

 

[thetrueman]

Thank you very much for this classic sharing. Just to request if it would be addition for serial ports modbus to be use with tablets as HMI. Thus we can experience the versatility of B4A power as a HMI user interface. I hope, I have asked in the proper way. Thanks.

 

[Peter Simpson]

Hello @thetrueman,

Just to request if it would be addition for serial ports modbus to be use with tablets as HMI.

This library wrap was WiFi only.

Below is another Modbus Master library that I wrapped, I will be releasing it shortly. This library did actually have both WiFi and serial, but I deliberately removed the serial part of the code simply because I had no viable way of testing serial Modbus communications 100% successfully, otherwise I would have kept the serial code in. I might look into it at some point, but for now I can't.

I do have an Modbus TCP simulator, I'll be releasing that library and example app. I now have a hardware actuator and also a hardware valve that both work over TCP. Sadly, I had no need for serial communications.

Coming soon: Below are screenshots from a new XUI Modbus Client library.

XUI (B4A) - Easy Modbus Client screen

XUI (B4J) - Easy Modbus Client screen

Enjoy

 

[MrKim]

Will this lib work in B4J or is this Android only?

 

[Peter Simpson]

Will this lib work in B4J or is this Android only?

This one is, yes.

The version mentioned in my post #6 above is a more advanced XUI version that I'll be releasing in the next few weeks. XUI versions connect via TCP.

I've also wrapped and am currently testing 2 more Modbus libraries. Those 2 libraries are for B4A (USB to Serial) and B4J (Serial) and connect via RS485 com ports directly, I'm currently testing these as well.

 

[amorosik]

Hello Everyone,
I've updated the library to V1.01. Please read carefully the PLEASE TAKE NOTE: section at the bottom of post #1 as the Initialize signature has changed and so has the library name.

Enjoy...

XUI (B4A/B4J) - Future cross-platform libraries:
I’ll be releasing a Modbus TCP Server (Slave) library that simulates Modbus hardware. I’ll also be releasing a second Modbus TCP Client (Master) library for reading and writing to and from Modbus hardware. This library uses FC23 without chaining.

Were you able to do anything for the Modbus server part to simulate a Modbus hardware?

 

[Peter Simpson]

Hello

Were you able to do anything for the Modbus server part to simulate a Modbus hardware?

Below is a screenshot of my very basic test application, so yes, kind of. You can write to the apps coils and registers and read then them back with ease. I supposed could make it like the three free software simulators that I already have which shows you each and every single coil and register on the server, but I don't really have the time to make an entire app just for that whan I already have this test app and three free apps that all do the same thing, oh yes and a hardware tester now too. Creating an ESP32 solution would be relatively simple to achieve using B4R.

Screenshot:

Server logs:
[CODE lang="b4x" title="Modbus server logs"]Master read 14 Discrete Inputs starting at 0 (10001+)
Input Value: true
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Master read 14 Input Registers starting at 0 (30001+)
Val: 502
Val: 1150
Val: 42
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Master read 14 Coils starting at 0 (00001+)
Coil Value: true
Coil Value: false
Coil Value: true
Coil Value: false
Coil Value: false
Coil Value: true
Coil Value: false
Coil Value: false
Coil Value: false
Coil Value: false
Coil Value: false
Coil Value: false
Coil Value: false
Coil Value: false
Master wrote to coil 0 (00001+): true
Master read 14 Holding Registers starting at 0 (40001+)
Val: 1963
Val: 1971
Val: 2006
Val: 12345
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Master wrote 2 registers starting at 100 (40001+)
Val: 17142
Val: 58982
Master read 2 Holding Registers starting at 100 (40001+)
Val: 17142
Val: 58982
Master wrote to register 1 (40001+): 123
Master wrote 3 registers starting at 3 (40001+)
Val: 100
Val: 200
Val: 300
Master wrote 3 registers starting at 10 (40001+)
Val: 123
Val: 456
Val: 789
Master read 3 Holding Registers starting at 10 (40001+)
Val: 123
Val: 456
Val: 789
Master read 14 Discrete Inputs starting at 0 (10001+)
Input Value: true
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Input Value: false
Master wrote to coil 0 (00001+): true
Master read 14 Input Registers starting at 0 (30001+)
Val: 502
Val: 1150
Val: 42
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Val: 0
Master read 14 Coils starting at 0 (00001+)
Coil Value: true
Coil Value: false
Coil Value: true
Coil Value: false
Coil Value: false
Coil Value: true
Coil Value: false
Coil Value: false
Coil Value: false
Coil Value: false
Coil Value: false
Coil Value: false
Coil Value: false
Coil Value: false
Master wrote 10 coils starting at 0 (00001+)
Coil Value: true
Coil Value: false
Coil Value: true
Coil Value: false
Coil Value: true
Coil Value: false
Coil Value: true
Coil Value: false
Coil Value: true
Coil Value: false
Master wrote 3 registers starting at 10 (40001+)
Val: 123
Val: 456
Val: 789
Master read 3 Holding Registers starting at 10 (40001+)
Val: 123
Val: 456
Val: 789
Master wrote 3 registers starting at 3 (40001+)
Val: 100
Val: 200
Val: 300
Master read 2 Holding Registers starting at 100 (40001+)
Val: 17142
Val: 58982
Master wrote 2 registers starting at 100 (40001+)
Val: 17142
Val: 58982
Master wrote to register 1 (40001+): 123
Master read 14 Holding Registers starting at 0 (40001+)
Val: 1963
Val: 123
Val: 2006
Val: 100
Val: 200
Val: 300
Val: 0
Val: 0
Val: 0
Val: 0
Val: 123
Val: 456
Val: 789
Val: 0
[/CODE]

Currently beta testing a serial/com port version of modbus master/client library that I wrapped and enhanced, I intend on releasing it shortly.


Enjoy...