1LIBMODBUS(7)                   Libmodbus Manual                   LIBMODBUS(7)
2
3
4

NAME

6       libmodbus - a fast and portable Modbus library
7

SYNOPSIS

9       #include <modbus.h>
10
11       cc `pkg-config --cflags --libs libmodbus` files
12

DESCRIPTION

14       libmodbus is a library to send/receive data with a device which
15       respects the Modbus protocol. This library contains various backends to
16       communicate over different networks (eg. serial in RTU mode or Ethernet
17       in TCP/IPv6). The http://www.modbus.org site provides documentation
18       about the protocol at http://www.modbus.org/specs.php.
19
20       libmodbus provides an abstraction of the lower communication layers and
21       offers the same API on all supported platforms.
22
23       This documentation presents an overview of libmodbus concepts,
24       describes how libmodbus abstracts Modbus communication with different
25       hardware and platforms and provides a reference manual for the
26       functions provided by the libmodbus library.
27
28   Contexts
29       The Modbus protocol contains many variants (eg. serial RTU or Ehternet
30       TCP), to ease the implementation of a variant, the library was designed
31       to use a backend for each variant. The backends are also a convenient
32       way to fulfill other requirements (eg. real-time operations). Each
33       backend offers a specific function to create a new modbus_t context.
34       The modbus_t context is an opaque structure containing all necessary
35       information to establish a connection with others Modbus devices
36       according to the selected variant.
37
38       You can choose the best context for your needs among:
39
40       RTU Context
41           The RTU backend (Remote Terminal Unit) is used in serial
42           communication and makes use of a compact, binary representation of
43           the data for protocol communication. The RTU format follows the
44           commands/data with a cyclic redundancy check checksum as an error
45           check mechanism to ensure the reliability of data. Modbus RTU is
46           the most common implementation available for Modbus. A Modbus RTU
47           message must be transmitted continuously without inter-character
48           hesitations (extract from Wikipedia, Modbus,
49           http://en.wikipedia.org/wiki/Modbus (as of Mar. 13, 2011, 20:51
50           GMT).
51
52           The Modbus RTU framing calls a slave, a device/service which handle
53           Modbus requests, and a master, a client which send requests. The
54           communication is always initiated by the master.
55
56           Many Modbus devices can be connected together on the same physical
57           link so you need to define which slave is concerned by the message
58           with modbus_set_slave(3). If you’re running a slave, the slave
59           number is used to filter messages.
60
61           Create a Modbus RTU context
62               modbus_new_rtu(3)
63
64           Set the serial mode
65               modbus_rtu_get_serial_mode(3) modbus_rtu_set_serial_mode(3)
66
67       TCP (IPv4) Context
68           The TCP backend implements a Modbus variant used for communications
69           over TCP/IPv4 networks. It does not require a checksum calculation
70           as lower layer takes care of the same.
71
72           Create a Modbus TCP context
73               modbus_new_tcp(3)
74
75       TCP PI (IPv4 and IPv6) Context
76           The TCP PI (Protocol Indepedent) backend implements a Modbus
77           variant used for communications over TCP IPv4 and IPv6 networks. It
78           does not require a checksum calculation as lower layer takes care
79           of the same.
80
81           Contrary to the TCP IPv4 only backend, the TCP PI backend offers
82           hostname resolution but it consumes about 1Kb of additional memory.
83
84           Create a Modbus TCP context
85               modbus_new_tcp_pi(3)
86
87       Common
88           Before using any libmodbus functions, the caller must allocate and
89           initialize a modbus_t context with functions explained above, then
90           the following functions are provided to modify and free a context:
91
92           Free libmodbus context
93               modbus_free(3)
94
95           Context setters and getters
96               modbus_get_byte_timeout(3) modbus_set_byte_timeout(3)
97               modbus_set_debug(3) modbus_set_error_recovery(3)
98               modbus_get_header_length(3) modbus_get_response_timeout(3)
99               modbus_set_response_timeout(3) modbus_set_slave(3)
100               modbus_set_socket(3) modbus_get_socket(3)
101
102           A libmodbus context is thread safe and may be shared among as many
103           application threads as necessary, without any additional locking
104           required on the part of the caller.
105
106           Macros for data manipulation
107               MODBUS_GET_HIGH_BYTE(data), extracts the high byte from a byte
108               MODBUS_GET_LOW_BYTE(data), extracts the low byte from a byte
109               MODBUS_GET_INT32_FROM_INT16(tab_int16, index), builds an int32
110               from the two first int16 starting at tab_int16[index]
111               MODBUS_GET_INT16_FROM_INT8(tab_int8, index), builds an int16
112               from the two first int8 starting at tab_int8[index]
113               MODBUS_SET_INT16_TO_INT8(tab_int8, index, value), set an int16
114               value into the two first bytes starting at tab_int8[index]
115
116           Functions for data manipulation
117               modbus_set_bits_from_byte(3) modbus_set_bits_from_bytes(3)
118               modbus_get_byte_from_bits(3) modbus_get_float(3)
119               modbus_set_float(3)
120
121   Connection
122       The following functions are provided to establish and close a
123       connection with Modbus devices:
124
125       Establish a connection
126           modbus_connect(3)
127
128       Close a connection
129           modbus_close(3)
130
131       Flush a connection
132           modbus_flush(3)
133
134   Client
135       The Modbus protocol defines different data types and functions to read
136       and write them from/to remote devices. The following functions are used
137       by the clients to send Modbus requests:
138
139       Read data
140           modbus_read_bits(3) modbus_read_input_bits(3)
141           modbus_read_registers(3) modbus_read_input_registers(3)
142           modbus_report_slave_id(3)
143
144       Write data
145           modbus_write_bit(3) modbus_write_register(3) modbus_write_bits(3)
146           modbus_write_registers(3)
147
148       Write and read data
149           modbus_write_and_read_registers(3)
150
151       Raw requests
152           modbus_send_raw_request(3) modbus_receive_confirmation(3)
153
154       Reply an exception
155           modbus_reply_exception(3)
156
157   Server
158       The server is waiting for request from clients and must answer when it
159       is concerned by the request. The libmodbus offers the following
160       functions to handle requests:
161
162       Data mapping: modbus_mapping_new(3) modbus_mapping_free(3)
163
164       Receive
165           modbus_receive(3)
166
167       Reply
168           modbus_reply(3) modbus_reply_exception(3)
169

ERROR HANDLING

171       The libmodbus functions handle errors using the standard conventions
172       found on POSIX systems. Generally, this means that upon failure a
173       libmodbus function shall return either a NULL value (if returning a
174       pointer) or a negative value (if returning an integer), and the actual
175       error code shall be stored in the errno variable.
176
177       The modbus_strerror() function is provided to translate
178       libmodbus-specific error codes into error message strings; for details
179       refer to modbus_strerror(3).
180

MISCELLANEOUS

182       The LIBMODBUS_VERSION_STRING constant indicates the libmodbus version
183       the program has been compiled against. The variables
184       libmodbus_version_major, libmodbus_version_minor,
185       libmodbus_version_micro give the version the program is linked against.
186

AUTHORS

188       The libmodbus documentation was written by Stéphane Raimbault
189       <stephane.raimbault@gmail.com[1]>
190

RESOURCES

192       Main web site: http://www.libmodbus.org/
193
194       Report bugs on the issue tracker at
195       http://github.com/stephane/libmodbus/issues.
196

COPYING

198       Free use of this software is granted under the terms of the GNU Lesser
199       General Public License (LGPL v2.1+). For details see the files COPYING
200       and COPYING.LESSER included with the libmodbus distribution.
201

NOTES

203        1. stephane.raimbault@gmail.com
204           mailto:stephane.raimbault@gmail.com
205
206
207
208libmodbus 3.0.8                   07/31/2019                      LIBMODBUS(7)
Impressum