LIBMODBUS(7)

💖 LIBMODBUS(7) — the libmodbus manual page, section 7, bestie edition 💖

okay so. welcome to the libmodbus manual, section 7 of the libmodbus Manual. yes it's a real manpage, no it's not boring, sit down, grab a boba, we're doing this. 🧋✨

🌈 NAME 🌈

libmodbus — a fast and portable Modbus library. that's it. that's the whole vibe. fast. portable. iconic. 💅

✨ SYNOPSIS ✨

#include <modbus.h>

cc `pkg-config --cflags --libs libmodbus` files

like, that's literally how you get in. compile with that pkg-config line and you're in the club, no cap. 🫶

🦋 DESCRIPTION 🦋

so libmodbus is a library for sending and receiving data with a device that respects the Modbus protocol. she contains various backends to communicate over different networks — for example, serial in RTU mode, or Ethernet in TCP/IPv6. if you want the actual protocol lore, the site http://www.modbus.org has docs at http://www.modbus.org/specs.php. go read, bestie, I'll wait. 💜

libmodbus gives you an abstraction of the lower communication layers and offers the same API on all supported platforms. same energy everywhere. that's the whole point. 👑

this documentation is giving you an overview of libmodbus concepts, explaining how libmodbus abstracts Modbus communication with different hardware and platforms, and providing a reference manual for the functions the libmodbus library provides. all three. we're doing it all. 🎀

🧚 Contexts

the Modbus protocol has so many variants (serial RTU, Ethernet TCP, the list goes on), so to make implementing a variant easier, the library was designed to use a backend for each variant. backends are also a convenient way to fulfill other requirements — like real-time operations, for instance. each backend offers a specific function to create a new modbus_t context. the modbus_t context is an opaque structure containing all the necessary information to establish a connection with other Modbus devices according to the selected variant. she's opaque. she's mysterious. she knows everything. 💅

you can choose the best context for your needs among these:

RTU Context

the RTU backend (Remote Terminal Unit) is used in serial communication and makes use of a compact, binary representation of the data for protocol communication. the RTU format follows the commands/data with a cyclic redundancy check checksum as an error check mechanism, to ensure the reliability of data. Modbus RTU is the most common implementation available for Modbus, periodt. a Modbus RTU message must be transmitted continuously without inter-character hesitations. (extract from Wikipedia, Modbus, http://en.wikipedia.org/wiki/Modbus (as of Mar. 13, 2011, 20:51 GMT).)

the Modbus RTU framing calls a slave a device/service which handles Modbus requests, and a master a client which sends requests. the communication is always initiated by the master. master makes the first move, always. 😌

many Modbus devices can be connected together on the same physical link, so before sending a message you must set the slave (receiver) with modbus_set_slave(3). if you're running a slave, its slave number will be used to filter received messages.

the libmodbus implementation of RTU isn't time based as stated in the original Modbus specification — instead, all bytes are sent as fast as possible and a response or an indication is considered complete when all expected characters have been received. this implementation offers very fast communication, but ⚠️ you must take care to set a response timeout of slaves less than the response timeout of master (otherwise other slaves may ignore master requests when one of the slave is not responding). write that down. 🫡

Create a Modbus RTU context

• modbus_new_rtu(3)

Set the serial mode

• modbus_rtu_get_serial_mode(3) modbus_rtu_set_serial_mode(3)
• modbus_rtu_get_rts(3) modbus_rtu_set_rts(3)
• modbus_rtu_set_custom_rts(3) modbus_rtu_get_rts_delay(3)
• modbus_rtu_set_rts_delay(3)

TCP (IPv4) Context

the TCP backend implements a Modbus variant used for communications over TCP/IPv4 networks. it does not require a checksum calculation, because the lower layer takes care of the same. she's handled. don't worry about it. ✨

Create a Modbus TCP context

• modbus_new_tcp(3)

TCP PI (IPv4 and IPv6) Context

the TCP PI (Protocol Independent) backend implements a Modbus variant used for communications over TCP IPv4 and IPv6 networks. it does not require a checksum calculation, as the lower layer takes care of the same.

contrary to the TCP IPv4 only backend, the TCP PI backend offers hostname resolution, but it consumes about 1Kb of additional memory. trade-offs, bestie. 1Kb for hostnames. worth it? your call. 💀

Create a Modbus TCP context

• modbus_new_tcp_pi(3)

Common

before using any libmodbus functions, the caller must allocate and initialize a modbus_t context with the functions explained above. then, the following functions are provided to modify and free a context:

Free libmodbus context

• modbus_free(3)

Set slave ID

• modbus_set_slave(3)

Enable debug mode

• modbus_set_debug(3)

Timeout settings

• modbus_get_byte_timeout(3) modbus_set_byte_timeout(3)
• modbus_get_response_timeout(3) modbus_set_response_timeout(3)
• modbus_get_indication_timeout(3) modbus_set_indication_timeout(3)

Error recovery mode

• modbus_set_error_recovery(3)

Setter/getter of internal socket

• modbus_set_socket(3) modbus_get_socket(3)

Information about header

• modbus_get_header_length(3)

Macros for data manipulation

• MODBUS_GET_HIGH_BYTE(data) — extracts the high byte from a byte
• MODBUS_GET_LOW_BYTE(data) — extracts the low byte from a byte
• MODBUS_GET_INT64_FROM_INT16(tab_int16, index) — builds an int64 from the four first int16 starting at tab_int16[index]
• MODBUS_GET_INT32_FROM_INT16(tab_int16, index) — builds an int32 from the two first int16 starting at tab_int16[index]
• MODBUS_GET_INT16_FROM_INT8(tab_int8, index) — builds an int16 from the two first int8 starting at tab_int8[index]
• MODBUS_SET_INT16_TO_INT8(tab_int8, index, value) — set an int16 value into the two first bytes starting at tab_int8[index]
• MODBUS_SET_INT32_TO_INT16(tab_int16, index, value) — set an int32 value into the two first int16 starting at tab_int16[index]
• MODBUS_SET_INT64_TO_INT16(tab_int16, index, value) — set an int64 value into the four first int16 starting at tab_int16[index]

Handling of bits and bytes

• modbus_set_bits_from_byte(3) modbus_set_bits_from_bytes(3)
• modbus_get_byte_from_bits(3)

Set or get float numbers

• modbus_get_float_abcd(3) modbus_set_float_abcd(3)
• modbus_get_float_badc(3) modbus_set_float_badc(3)
• modbus_get_float_cdab(3) modbus_set_float_cdab(3)
• modbus_get_float_dcba(3) modbus_set_float_dcba(3)
• modbus_get_float(3) (deprecated) modbus_set_float(3) (deprecated)

bestie, those last two are marked deprecated. they still exist, they still work, but like… read the room. use the abcd/badc/cdab/dcba versions. 🙈

🌸 Connection

the following functions are provided to establish and close a connection with Modbus devices:

Establish a connection

• modbus_connect(3)

Close a connection

• modbus_close(3)

Flush a connection

• modbus_flush(3)

💅 Client

the Modbus protocol defines different data types and functions to read and write them from/to remote devices. the following functions are used by the clients to send Modbus requests:

Read data

• modbus_read_bits(3) modbus_read_input_bits(3)
• modbus_read_registers(3) modbus_read_input_registers(3)
• modbus_report_slave_id(3)

Write data

• modbus_write_bit(3) modbus_write_register(3) modbus_write_bits(3)
• modbus_write_registers(3)

Write and read data

• modbus_write_and_read_registers(3)

Raw requests

• modbus_send_raw_request(3) modbus_receive_confirmation(3)

Reply an exception

• modbus_reply_exception(3)

👑 Server

the server is waiting for requests from clients and must answer when it is concerned by the request. she's on standby. she's ready. she's the main character. 💅

in TCP mode, you must not use the usual modbus_connect(3) to establish the connection — instead you use a pair of accept/listen calls:

• modbus_tcp_listen(3) modbus_tcp_accept(3) modbus_tcp_pi_listen(3)
• modbus_tcp_pi_accept(3)

then the data can be received with:

• modbus_receive(3)

and a response can be send with:

• modbus_reply(3) modbus_reply_exception(3)

to handle the mapping of your Modbus data, you must use:

• modbus_mapping_new(3) modbus_mapping_free(3)

😭 ERROR HANDLING 😭

the libmodbus functions handle errors using the standard conventions found on POSIX systems. generally, this means that upon failure a libmodbus function shall return either a NULL value (if returning a pointer) or a negative value (if returning an integer), and the actual error code shall be stored in the errno variable. errno is literally holding the receipts. 🧾

the modbus_strerror() function is provided to translate libmodbus-specific error codes into error message strings. for details, refer to modbus_strerror(3).

⭐ MISCELLANEOUS ⭐

the LIBMODBUS_VERSION_STRING constant indicates the libmodbus version the program has been compiled against. the variables libmodbus_version_major, libmodbus_version_minor, libmodbus_version_micro give the version the program is linked against. compiled vs linked. two different things. know the difference, iykyk. 👀

🫶 AUTHORS 🫶

the libmodbus documentation was written by Stéphane Raimbault <stephane.raimbault@gmail.com>. thank you for your service, legend. 🎀

💜 RESOURCES 💜

main web site: http://www.libmodbus.org/

report bugs on the issue tracker at http://github.com/stephane/libmodbus/issues. go snitch (kindly). 🐛

🌟 COPYING 🌟

free use of this software is granted under the terms of the GNU Lesser General Public License (LGPL v2.1+). for details see the file COPYING.LESSER included with the libmodbus distribution. read the license, bestie, it's free but it's not free free, you know? ⚖️

---

and that's the whole page, babes. this was libmodbus v3.1.6, dated 11/17/2025, from the libmodbus Manual — go forth and speak Modbus, you absolute icon. 💖✨🦋🌸👑🌈⭐💅