1LIBMODBUS(7) libmodbus Manual LIBMODBUS(7)
2
6 libmodbus - a fast and portable Modbus library
7
9 #include <modbus.h>
10 cc `pkg-config --cflags --libs libmodbus` files
12
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 libmodbus provides an abstraction of the lower communication layers and
21 offers the same API on all supported platforms.
22 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 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 You can choose the best context for your needs among:
39 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 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 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 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 Create a Modbus RTU context
71 modbus_new_rtu(3)
72 Set the serial mode
74 modbus_rtu_get_serial_mode(3) modbus_rtu_set_serial_mode(3)
75 modbus_rtu_get_rts(3) modbus_rtu_set_rts(3)
76 modbus_rtu_set_custom_rts(3) modbus_rtu_get_rts_delay(3)
77 modbus_rtu_set_rts_delay(3)
78 TCP (IPv4) Context
80 The TCP backend implements a Modbus variant used for communications
81 over TCP/IPv4 networks. It does not require a checksum calculation
82 as lower layer takes care of the same.
83 Create a Modbus TCP context
85 modbus_new_tcp(3)
86 TCP PI (IPv4 and IPv6) Context
88 The TCP PI (Protocol Independent) backend implements a Modbus
89 variant used for communications over TCP IPv4 and IPv6 networks. It
90 does not require a checksum calculation as lower layer takes care
91 of the same.
92 Contrary to the TCP IPv4 only backend, the TCP PI backend offers
94 hostname resolution but it consumes about 1Kb of additional memory.
95 Create a Modbus TCP context
97 modbus_new_tcp_pi(3)
98 Common
100 Before using any libmodbus functions, the caller must allocate and
101 initialize a modbus_t context with functions explained above, then
102 the following functions are provided to modify and free a context:
103 Free libmodbus context
105 modbus_free(3)
106 Set slave ID
108 modbus_set_slave(3)
109 Enable debug mode
111 modbus_set_debug(3)
112 Timeout settings
114 modbus_get_byte_timeout(3) modbus_set_byte_timeout(3)
115 modbus_get_response_timeout(3) modbus_set_response_timeout(3)
116 modbus_get_indication_timeout(3)
117 modbus_set_indication_timeout(3)
118 Error recovery mode
120 modbus_set_error_recovery(3)
121 Setter/getter of internal socket
123 modbus_set_socket(3) modbus_get_socket(3)
124 Information about header
126 modbus_get_header_length(3)
127 Macros for data manipulation
129 • MODBUS_GET_HIGH_BYTE(data), extracts the high byte from a
131 byte
132 • MODBUS_GET_LOW_BYTE(data), extracts the low byte from a
134 byte
135 • MODBUS_GET_INT64_FROM_INT16(tab_int16, index), builds an
137 int64 from the four first int16 starting at
138 tab_int16[index]
139 • MODBUS_GET_INT32_FROM_INT16(tab_int16, index), builds an
141 int32 from the two first int16 starting at tab_int16[index]
142 • MODBUS_GET_INT16_FROM_INT8(tab_int8, index), builds an
144 int16 from the two first int8 starting at tab_int8[index]
145 • MODBUS_SET_INT16_TO_INT8(tab_int8, index, value), set an
147 int16 value into the two first bytes starting at
148 tab_int8[index]
149 • MODBUS_SET_INT32_TO_INT16(tab_int16, index, value), set an
151 int32 value into the two first int16 starting at
152 tab_int16[index]
153 • MODBUS_SET_INT64_TO_INT16(tab_int16, index, value), set an
155 int64 value into the four first int16 starting at
156 tab_int16[index]
157 Handling of bits and bytes
159 modbus_set_bits_from_byte(3) modbus_set_bits_from_bytes(3)
160 modbus_get_byte_from_bits(3)
161 Set or get float numbers
163 modbus_get_float_abcd(3) modbus_set_float_abcd(3)
164 modbus_get_float_badc(3) modbus_set_float_badc(3)
165 modbus_get_float_cdab(3) modbus_set_float_cdab(3)
166 modbus_get_float_dcba(3) modbus_set_float_dcba(3)
167 modbus_get_float(3) (deprecated) modbus_set_float(3)
168 (deprecated)
169 Connection
171 The following functions are provided to establish and close a
172 connection with Modbus devices:
173 Establish a connection
175 modbus_connect(3)
176 Close a connection
178 modbus_close(3)
179 Flush a connection
181 modbus_flush(3)
182 Client
184 The Modbus protocol defines different data types and functions to read
185 and write them from/to remote devices. The following functions are used
186 by the clients to send Modbus requests:
187 Read data
189 modbus_read_bits(3) modbus_read_input_bits(3)
190 modbus_read_registers(3) modbus_read_input_registers(3)
191 modbus_report_slave_id(3)
192 Write data
194 modbus_write_bit(3) modbus_write_register(3) modbus_write_bits(3)
195 modbus_write_registers(3)
196 Write and read data
198 modbus_write_and_read_registers(3)
199 Raw requests
201 modbus_send_raw_request(3) modbus_receive_confirmation(3)
202 Reply an exception
204 modbus_reply_exception(3)
205 Server
207 The server is waiting for request from clients and must answer when it
208 is concerned by the request.
209 In TCP mode, you must not use the usual modbus_connect(3) to establish
211 the connection but a pair of accept/listen calls
212 modbus_tcp_listen(3) modbus_tcp_accept(3) modbus_tcp_pi_listen(3)
213 modbus_tcp_pi_accept(3)
214 then the data can be received with
216 modbus_receive(3)
217 and a response can be send with
219 modbus_reply(3) modbus_reply_exception(3)
220 To handle the mapping of your Modbus data, you must use:
222 modbus_mapping_new(3) modbus_mapping_free(3)
223
225 The libmodbus functions handle errors using the standard conventions
226 found on POSIX systems. Generally, this means that upon failure a
227 libmodbus function shall return either a NULL value (if returning a
228 pointer) or a negative value (if returning an integer), and the actual
229 error code shall be stored in the errno variable.
230 The modbus_strerror() function is provided to translate
232 libmodbus-specific error codes into error message strings; for details
233 refer to modbus_strerror(3).
234
236 The LIBMODBUS_VERSION_STRING constant indicates the libmodbus version
237 the program has been compiled against. The variables
238 libmodbus_version_major, libmodbus_version_minor,
239 libmodbus_version_micro give the version the program is linked against.
240
242 The libmodbus documentation was written by Stéphane Raimbault
243 <stephane.raimbault@gmail.com>
244
246 Main web site: http://www.libmodbus.org/
247 Report bugs on the issue tracker at
249 http://github.com/stephane/libmodbus/issues.
250
252 Free use of this software is granted under the terms of the GNU Lesser
253 General Public License (LGPL v2.1+). For details see the file
254 COPYING.LESSER included with the libmodbus distribution.
255libmodbus v3.1.6 07/21/2022 LIBMODBUS(7)