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 files `pkg-config --cflags --libs libmodbus`
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 Ethernet
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 other 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 before sending a message, you must set the slave (receiver)
58           with modbus_set_slave(3). If you’re running a slave, its slave
59           number will be used to filter received messages.
60
61           The libmodbus implementation of RTU isn’t time based as stated in
62           original Modbus specification, instead all bytes are sent as fast
63           as possible and a response or an indication is considered complete
64           when all expected characters have been received. This
65           implementation offers very fast communication but you must take
66           care to set a response timeout of slaves less than response timeout
67           of master (ortherwise other slaves may ignore master requests when
68           one of the slave is not responding).
69
70           Create a Modbus RTU context
71
72               •   modbus_new_rtu(3)
73
74           Set the serial mode
75
76               •   modbus_rtu_get_serial_mode(3)
77
78               •   modbus_rtu_set_serial_mode(3)
79
80               •   modbus_rtu_get_rts(3)
81
82               •   modbus_rtu_set_rts(3)
83
84               •   modbus_rtu_set_custom_rts(3)
85
86               •   modbus_rtu_get_rts_delay(3)
87
88               •   modbus_rtu_set_rts_delay(3)
89
90       TCP (IPv4) Context
91           The TCP backend implements a Modbus variant used for communications
92           over TCP/IPv4 networks. It does not require a checksum calculation
93           as lower layer takes care of the same.
94
95           Create a Modbus TCP context
96
97               •   modbus_new_tcp(3)
98
99       TCP PI (IPv4 and IPv6) Context
100           The TCP PI (Protocol Independent) backend implements a Modbus
101           variant used for communications over TCP IPv4 and IPv6 networks. It
102           does not require a checksum calculation as lower layer takes care
103           of the same.
104
105           Contrary to the TCP IPv4 only backend, the TCP PI backend offers
106           hostname resolution but it consumes about 1Kb of additional memory.
107
108           Create a Modbus TCP context
109
110               •   modbus_new_tcp_pi(3)
111
112       Common
113           Before using any libmodbus functions, the caller must allocate and
114           initialize a modbus_t context with functions explained above, then
115           the following functions are provided to modify and free a context:
116
117           Free libmodbus context
118
119               •   modbus_free(3)
120
121           Set slave ID
122
123               •   modbus_set_slave(3)
124
125           Enable debug mode
126
127               •   modbus_set_debug(3)
128
129           Timeout settings
130
131               •   modbus_get_byte_timeout(3)
132
133               •   modbus_set_byte_timeout(3)
134
135               •   modbus_get_response_timeout(3)
136
137               •   modbus_set_response_timeout(3)
138
139           Error recovery mode
140
141               •   modbus_set_error_recovery(3)
142
143           Setter/getter of internal socket
144
145               •   modbus_set_socket(3)
146
147               •   modbus_get_socket(3)
148
149           Information about header
150
151               •   modbus_get_header_length(3)
152
153           Macros for data manipulation
154
155               •   MODBUS_GET_HIGH_BYTE(data), extracts the high byte from a
156                   byte
157
158               •   MODBUS_GET_LOW_BYTE(data), extracts the low byte from a
159                   byte
160
161               •   MODBUS_GET_INT64_FROM_INT16(tab_int16, index), builds an
162                   int64 from the four first int16 starting at
163                   tab_int16[index]
164
165               •   MODBUS_GET_INT32_FROM_INT16(tab_int16, index), builds an
166                   int32 from the two first int16 starting at tab_int16[index]
167
168               •   MODBUS_GET_INT16_FROM_INT8(tab_int8, index), builds an
169                   int16 from the two first int8 starting at tab_int8[index]
170
171               •   MODBUS_SET_INT16_TO_INT8(tab_int8, index, value), set an
172                   int16 value into the two first bytes starting at
173                   tab_int8[index]
174
175               •   MODBUS_SET_INT32_TO_INT16(tab_int16, index, value), set an
176                   int32 value into the two first int16 starting at
177                   tab_int16[index]
178
179               •   MODBUS_SET_INT64_TO_INT16(tab_int16, index, value), set an
180                   int64 value into the four first int16 starting at
181                   tab_int16[index]
182
183           Handling of bits and bytes
184
185               •   modbus_set_bits_from_byte(3)
186
187               •   modbus_set_bits_from_bytes(3)
188
189               •   modbus_get_byte_from_bits(3)
190
191           Set or get float numbers
192
193               •   modbus_get_float_abcd(3)
194
195               •   modbus_set_float_abcd(3)
196
197               •   modbus_get_float_badc(3)
198
199               •   modbus_set_float_badc(3)
200
201               •   modbus_get_float_cdab(3)
202
203               •   modbus_set_float_cdab(3)
204
205               •   modbus_get_float_dcba(3)
206
207               •   modbus_set_float_dcba(3)
208
209               •   modbus_get_float(3) (deprecated)
210
211               •   modbus_set_float(3) (deprecated)
212
213   Connection
214       The following functions are provided to establish and close a
215       connection with Modbus devices:
216
217       Establish a connection
218
219           •   modbus_connect(3)
220
221       Close a connection
222
223           •   modbus_close(3)
224
225       Flush a connection
226
227           •   modbus_flush(3)
228
229   Client
230       The Modbus protocol defines different data types and functions to read
231       and write them from/to remote devices. The following functions are used
232       by the clients to send Modbus requests:
233
234       Read data
235
236           •   modbus_read_bits(3)
237
238           •   modbus_read_input_bits(3)
239
240           •   modbus_read_registers(3)
241
242           •   modbus_read_input_registers(3)
243
244           •   modbus_report_slave_id(3)
245
246       Write data
247
248           •   modbus_write_bit(3)
249
250           •   modbus_write_register(3)
251
252           •   modbus_write_bits(3)
253
254           •   modbus_write_registers(3)
255
256       Write and read data
257
258           •   modbus_write_and_read_registers(3)
259
260       Raw requests
261
262           •   modbus_send_raw_request(3)
263
264           •   modbus_receive_confirmation(3)
265
266       Reply an exception
267
268           •   modbus_reply_exception(3)
269
270   Server
271       The server is waiting for request from clients and must answer when it
272       is concerned by the request. The libmodbus offers the following
273       functions to handle requests:
274
275       Data mapping
276
277           •   modbus_mapping_new(3)
278
279           •   modbus_mapping_free(3)
280
281       Receive
282
283           •   modbus_receive(3)
284
285       Reply
286
287           •   modbus_reply(3)
288
289           •   modbus_reply_exception(3)
290

ERROR HANDLING

292       The libmodbus functions handle errors using the standard conventions
293       found on POSIX systems. Generally, this means that upon failure a
294       libmodbus function shall return either a NULL value (if returning a
295       pointer) or a negative value (if returning an integer), and the actual
296       error code shall be stored in the errno variable.
297
298       The modbus_strerror() function is provided to translate
299       libmodbus-specific error codes into error message strings; for details
300       refer to modbus_strerror(3).
301

MISCELLANEOUS

303       The LIBMODBUS_VERSION_STRING constant indicates the libmodbus version
304       the program has been compiled against. The variables
305       libmodbus_version_major, libmodbus_version_minor,
306       libmodbus_version_micro give the version the program is linked against.
307

AUTHORS

309       The libmodbus documentation was written by Stéphane Raimbault
310       <stephane.raimbault@gmail.com>
311

RESOURCES

313       Main web site: http://www.libmodbus.org/
314
315       Report bugs on the issue tracker at
316       http://github.com/stephane/libmodbus/issues.
317

COPYING

319       Free use of this software is granted under the terms of the GNU Lesser
320       General Public License (LGPL v2.1+). For details see the file
321       COPYING.LESSER included with the libmodbus distribution.
322
323
324
325libmodbus v3.1.7                  07/20/2023                      LIBMODBUS(7)