'\" t
.\"     Title: libmodbus
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/28/2020
.\"    Manual: libmodbus Manual
.\"    Source: libmodbus v3.1.6
.\"  Language: English
.\"
.TH "LIBMODBUS" "7" "02/28/2020" "libmodbus v3\&.1\&.6" "libmodbus Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
libmodbus \- a fast and portable Modbus library
.SH "SYNOPSIS"
.sp
\fB#include <modbus\&.h>\fR
.sp
\fBcc\fR `pkg\-config \-\-cflags \-\-libs libmodbus` \fIfiles\fR
.SH "DESCRIPTION"
.sp
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\&.
.sp
libmodbus provides an abstraction of the lower communication layers and offers the same API on all supported platforms\&.
.sp
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\&.
.SS "Contexts"
.sp
The Modbus protocol contains many variants (eg\&. serial RTU or Ethernet 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 \fImodbus_t\fR context\&. The \fImodbus_t\fR context is an opaque structure containing all necessary information to establish a connection with other Modbus devices according to the selected variant\&.
.sp
You can choose the best context for your needs among:
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBRTU Context\fR
.RS 4
.sp
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)\&.
.sp
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\&.
.sp
Many Modbus devices can be connected together on the same physical link so before sending a message, you must set the slave (receiver) with \fBmodbus_set_slave\fR(3)\&. If you\(cqre running a slave, its slave number will be used to filter received messages\&.
.sp
The libmodbus implementation of RTU isn\(cqt time based as stated in 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 response timeout of master (ortherwise other slaves may ignore master requests when one of the slave is not responding)\&.
.PP
Create a Modbus RTU context
.RS 4
\fBmodbus_new_rtu\fR(3)
.RE
.PP
Set the serial mode
.RS 4
\fBmodbus_rtu_get_serial_mode\fR(3)
\fBmodbus_rtu_set_serial_mode\fR(3)
\fBmodbus_rtu_get_rts\fR(3)
\fBmodbus_rtu_set_rts\fR(3)
\fBmodbus_rtu_set_custom_rts\fR(3)
\fBmodbus_rtu_get_rts_delay\fR(3)
\fBmodbus_rtu_set_rts_delay\fR(3)
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTCP (IPv4) Context\fR
.RS 4
.sp
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\&.
.PP
Create a Modbus TCP context
.RS 4
\fBmodbus_new_tcp\fR(3)
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTCP PI (IPv4 and IPv6) Context\fR
.RS 4
.sp
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 lower layer takes care of the same\&.
.sp
Contrary to the TCP IPv4 only backend, the TCP PI backend offers hostname resolution but it consumes about 1Kb of additional memory\&.
.PP
Create a Modbus TCP context
.RS 4
\fBmodbus_new_tcp_pi\fR(3)
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBCommon\fR
.RS 4
.sp
Before using any libmodbus functions, the caller must allocate and initialize a \fImodbus_t\fR context with functions explained above, then the following functions are provided to modify and free a \fIcontext\fR:
.PP
Free libmodbus context
.RS 4
\fBmodbus_free\fR(3)
.RE
.PP
Set slave ID
.RS 4
\fBmodbus_set_slave\fR(3)
.RE
.PP
Enable debug mode
.RS 4
\fBmodbus_set_debug\fR(3)
.RE
.PP
Timeout settings
.RS 4
\fBmodbus_get_byte_timeout\fR(3)
\fBmodbus_set_byte_timeout\fR(3)
\fBmodbus_get_response_timeout\fR(3)
\fBmodbus_set_response_timeout\fR(3)
\fBmodbus_get_indication_timeout\fR(3)
\fBmodbus_set_indication_timeout\fR(3)
.RE
.PP
Error recovery mode
.RS 4
\fBmodbus_set_error_recovery\fR(3)
.RE
.PP
Setter/getter of internal socket
.RS 4
\fBmodbus_set_socket\fR(3)
\fBmodbus_get_socket\fR(3)
.RE
.PP
Information about header
.RS 4
\fBmodbus_get_header_length\fR(3)
.RE
.PP
Macros for data manipulation
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
MODBUS_GET_HIGH_BYTE(data), extracts the high byte from a byte
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
MODBUS_GET_LOW_BYTE(data), extracts the low byte from a byte
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
MODBUS_GET_INT64_FROM_INT16(tab_int16, index), builds an int64 from the four first int16 starting at tab_int16[index]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
MODBUS_GET_INT32_FROM_INT16(tab_int16, index), builds an int32 from the two first int16 starting at tab_int16[index]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
MODBUS_GET_INT16_FROM_INT8(tab_int8, index), builds an int16 from the two first int8 starting at tab_int8[index]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
MODBUS_SET_INT16_TO_INT8(tab_int8, index, value), set an int16 value into the two first bytes starting at tab_int8[index]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
MODBUS_SET_INT32_TO_INT16(tab_int16, index, value), set an int32 value into the two first int16 starting at tab_int16[index]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
MODBUS_SET_INT64_TO_INT16(tab_int16, index, value), set an int64 value into the four first int16 starting at tab_int16[index]
.RE
.RE
.PP
Handling of bits and bytes
.RS 4
\fBmodbus_set_bits_from_byte\fR(3)
\fBmodbus_set_bits_from_bytes\fR(3)
\fBmodbus_get_byte_from_bits\fR(3)
.RE
.PP
Set or get float numbers
.RS 4
\fBmodbus_get_float_abcd\fR(3)
\fBmodbus_set_float_abcd\fR(3)
\fBmodbus_get_float_badc\fR(3)
\fBmodbus_set_float_badc\fR(3)
\fBmodbus_get_float_cdab\fR(3)
\fBmodbus_set_float_cdab\fR(3)
\fBmodbus_get_float_dcba\fR(3)
\fBmodbus_set_float_dcba\fR(3)
\fBmodbus_get_float\fR(3)
(deprecated)
\fBmodbus_set_float\fR(3)
(deprecated)
.RE
.RE
.SS "Connection"
.sp
The following functions are provided to establish and close a connection with Modbus devices:
.PP
Establish a connection
.RS 4
\fBmodbus_connect\fR(3)
.RE
.PP
Close a connection
.RS 4
\fBmodbus_close\fR(3)
.RE
.PP
Flush a connection
.RS 4
\fBmodbus_flush\fR(3)
.RE
.SS "Client"
.sp
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:
.PP
Read data
.RS 4
\fBmodbus_read_bits\fR(3)
\fBmodbus_read_input_bits\fR(3)
\fBmodbus_read_registers\fR(3)
\fBmodbus_read_input_registers\fR(3)
\fBmodbus_report_slave_id\fR(3)
.RE
.PP
Write data
.RS 4
\fBmodbus_write_bit\fR(3)
\fBmodbus_write_register\fR(3)
\fBmodbus_write_bits\fR(3)
\fBmodbus_write_registers\fR(3)
.RE
.PP
Write and read data
.RS 4
\fBmodbus_write_and_read_registers\fR(3)
.RE
.PP
Raw requests
.RS 4
\fBmodbus_send_raw_request\fR(3)
\fBmodbus_receive_confirmation\fR(3)
.RE
.PP
Reply an exception
.RS 4
\fBmodbus_reply_exception\fR(3)
.RE
.SS "Server"
.sp
The server is waiting for request from clients and must answer when it is concerned by the request\&.
.PP
In TCP mode, you must not use the usual \fBmodbus_connect\fR(3) to establish the connection but a pair of accept/listen calls
.RS 4
\fBmodbus_tcp_listen\fR(3)
\fBmodbus_tcp_accept\fR(3)
\fBmodbus_tcp_pi_listen\fR(3)
\fBmodbus_tcp_pi_accept\fR(3)
.RE
.PP
then the data can be received with
.RS 4
\fBmodbus_receive\fR(3)
.RE
.PP
and a response can be send with
.RS 4
\fBmodbus_reply\fR(3)
\fBmodbus_reply_exception\fR(3)
.RE
.sp
To handle the mapping of your Modbus data, you must use: \fBmodbus_mapping_new\fR(3) \fBmodbus_mapping_free\fR(3)
.SH "ERROR HANDLING"
.sp
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 \fIerrno\fR variable\&.
.sp
The \fBmodbus_strerror()\fR function is provided to translate libmodbus\-specific error codes into error message strings; for details refer to \fBmodbus_strerror\fR(3)\&.
.SH "MISCELLANEOUS"
.sp
The \fILIBMODBUS_VERSION_STRING\fR constant indicates the libmodbus version the program has been compiled against\&. The variables \fIlibmodbus_version_major\fR, \fIlibmodbus_version_minor\fR, \fIlibmodbus_version_micro\fR give the version the program is linked against\&.
.SH "AUTHORS"
.sp
The libmodbus documentation was written by Stéphane Raimbault <stephane\&.raimbault@gmail\&.com>
.SH "RESOURCES"
.sp
Main web site: http://www\&.libmodbus\&.org/
.sp
Report bugs on the issue tracker at http://github\&.com/stephane/libmodbus/issues\&.
.SH "COPYING"
.sp
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\&.