Provided by: libmodbus-dev_3.0.6-2+deb9u1build0.18.04.1_amd64 
NAME
libmodbus - a fast and portable Modbus library
SYNOPSIS
#include <modbus.h>
cc `pkg-config --cflags --libs libmodbus` files
DESCRIPTION
libmodbus is a library to send/receive data with a device which respects the Modbus protocol. This
library contains various backends to communicate over different networks (eg. serial in RTU mode or
Ethernet in TCP/IPv6). The http://www.modbus.org site provides documentation about the protocol at
http://www.modbus.org/specs.php.
libmodbus provides an abstraction of the lower communication layers and offers the same API on all
supported platforms.
This documentation presents an overview of libmodbus concepts, describes how libmodbus abstracts Modbus
communication with different hardware and platforms and provides a reference manual for the functions
provided by the libmodbus library.
Contexts
The Modbus protocol contains many variants (eg. serial RTU or Ehternet TCP), to ease the implementation
of a variant, the library was designed to use a backend for each variant. The backends are also a
convenient way to fulfill other requirements (eg. real-time operations). Each backend offers a specific
function to create a new modbus_t context. The modbus_t context is an opaque structure containing all
necessary information to establish a connection with others Modbus devices according to the selected
variant.
You can choose the best context for your needs among:
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. 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 handle Modbus requests, and a master, a
client which send requests. The communication is always initiated by the master.
Many Modbus devices can be connected together on the same physical link so you need to define which
slave is concerned by the message with modbus_set_slave(3). If you’re running a slave, the slave
number is used to filter messages.
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)
TCP (IPv4) Context
The TCP backend implements a Modbus variant used for communications over TCP/IPv4 networks. It does
not require a checksum calculation as lower layer takes care of the same.
Create a Modbus TCP context
• modbus_new_tcp(3)
TCP PI (IPv4 and IPv6) Context
The TCP PI (Protocol Indepedent) backend implements a Modbus variant used for communications over TCP
IPv4 and IPv6 networks. It does not require a checksum calculation as 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.
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
functions explained above, then the following functions are provided to modify and free a context:
Free libmodbus context
• modbus_free(3)
Context setters and getters
• modbus_get_byte_timeout(3)
• modbus_set_byte_timeout(3)
• modbus_set_debug(3)
• modbus_set_error_recovery(3)
• modbus_get_header_length(3)
• modbus_get_response_timeout(3)
• modbus_set_response_timeout(3)
• modbus_set_slave(3)
• modbus_set_socket(3)
• modbus_get_socket(3)
A libmodbus context is thread safe and may be shared among as many application threads as necessary,
without any additional locking required on the part of the caller.
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_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]
Functions for data manipulation
• modbus_set_bits_from_byte(3)
• modbus_set_bits_from_bytes(3)
• modbus_get_byte_from_bits(3)
• modbus_get_float(3)
• modbus_set_float(3)
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 request from clients and must answer when it is concerned by the request. The
libmodbus offers the following functions to handle requests:
Data mapping
• modbus_mapping_new(3)
• modbus_mapping_free(3)
Receive
• modbus_receive(3)
Reply
• modbus_reply(3)
• modbus_reply_exception(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.
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.
AUTHORS
The libmodbus documentation was written by Stéphane Raimbault <stephane.raimbault@gmail.com[1]>
RESOURCES
Main web site: http://www.libmodbus.org/
Report bugs on the issue tracker at http://github.com/stephane/libmodbus/issues.
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 files COPYING and COPYING.LESSER included with the libmodbus distribution.
NOTES
1. stephane.raimbault@gmail.com
mailto:stephane.raimbault@gmail.com
libmodbus 3.0.6 12/03/2021 LIBMODBUS(7)