'\" t
.\"     Title: libmodbus
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 11/30/2016
.\"    Manual: Libmodbus Manual
.\"    Source: libmodbus 3.0.6
.\"  Language: English
.\"
.TH "LIBMODBUS" "7" "11/30/2016" "libmodbus 3\&.0\&.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 \m[blue]\fBhttp://www\&.modbus\&.org\fR\m[] site provides documentation about the protocol at \m[blue]\fBhttp://www\&.modbus\&.org/specs\&.php\fR\m[]\&.
.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 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 \fImodbus_t\fR context\&. The \fImodbus_t\fR context is an opaque structure containing all necessary information to establish a connection with others 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, \m[blue]\fBhttp://en\&.wikipedia\&.org/wiki/Modbus\fR\m[] (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 you need to define which slave is concerned by the message with \fBmodbus_set_slave\fR(3)\&. If you\(cqre running a slave, the slave number is used to filter messages\&.
.PP
Create a Modbus RTU context
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_new_rtu\fR(3)
.RE
.RE
.PP
Set the serial mode
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_rtu_get_serial_mode\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_rtu_set_serial_mode\fR(3)
.RE
.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
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_new_tcp\fR(3)
.RE
.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 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\&.
.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
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_new_tcp_pi\fR(3)
.RE
.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
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_free\fR(3)
.RE
.RE
.PP
Context setters and getters
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_get_byte_timeout\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_set_byte_timeout\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_set_debug\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_set_error_recovery\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_get_header_length\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_get_response_timeout\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_set_response_timeout\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_set_slave\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_set_socket\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_get_socket\fR(3)
.RE
.RE
.sp
A libmodbus \fIcontext\fR 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\&.
.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_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
.RE
.PP
Functions for data manipulation
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_set_bits_from_byte\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_set_bits_from_bytes\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_get_byte_from_bits\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_get_float\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_set_float\fR(3)
.RE
.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
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_connect\fR(3)
.RE
.RE
.PP
Close a connection
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_close\fR(3)
.RE
.RE
.PP
Flush a connection
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_flush\fR(3)
.RE
.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
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_read_bits\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_read_input_bits\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_read_registers\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_read_input_registers\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_report_slave_id\fR(3)
.RE
.RE
.PP
Write data
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_write_bit\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_write_register\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_write_bits\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_write_registers\fR(3)
.RE
.RE
.PP
Write and read data
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_write_and_read_registers\fR(3)
.RE
.RE
.PP
Raw requests
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_send_raw_request\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_receive_confirmation\fR(3)
.RE
.RE
.PP
Reply an exception
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_reply_exception\fR(3)
.RE
.RE
.SS "Server"
.sp
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:
.PP
Data mapping
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_mapping_new\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_mapping_free\fR(3)
.RE
.RE
.PP
Receive
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_receive\fR(3)
.RE
.RE
.PP
Reply
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_reply\fR(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmodbus_reply_exception\fR(3)
.RE
.RE
.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 \fImodbus_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\('ephane Raimbault <\m[blue]\fBstephane\&.raimbault@gmail\&.com\fR\m[]\&\s-2\u[1]\d\s+2>
.SH "RESOURCES"
.sp
Main web site: \m[blue]\fBhttp://www\&.libmodbus\&.org/\fR\m[]
.sp
Report bugs on the issue tracker at \m[blue]\fBhttp://github\&.com/stephane/libmodbus/issues\fR\m[]\&.
.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 files COPYING and COPYING\&.LESSER included with the libmodbus distribution\&.
.SH "NOTES"
.IP " 1." 4
stephane.raimbault@gmail.com
.RS 4
\%mailto:stephane.raimbault@gmail.com
.RE