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 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 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 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 Create a Modbus RTU context
62 modbus_new_rtu(3)
63 Set the serial mode
65 modbus_rtu_get_serial_mode(3) modbus_rtu_set_serial_mode(3)
66 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 Create a Modbus TCP context
73 modbus_new_tcp(3)
74 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 Contrary to the TCP IPv4 only backend, the TCP PI backend offers
82 hostname resolution but it consumes about 1Kb of additional memory.
83 Create a Modbus TCP context
85 modbus_new_tcp_pi(3)
86 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 Free libmodbus context
93 modbus_free(3)
94 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 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 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 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 Connection
122 The following functions are provided to establish and close a
123 connection with Modbus devices:
124 Establish a connection
126 modbus_connect(3)
127 Close a connection
129 modbus_close(3)
130 Flush a connection
132 modbus_flush(3)
133 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 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 Write data
145 modbus_write_bit(3) modbus_write_register(3) modbus_write_bits(3)
146 modbus_write_registers(3)
147 Write and read data
149 modbus_write_and_read_registers(3)
150 Raw requests
152 modbus_send_raw_request(3) modbus_receive_confirmation(3)
153 Reply an exception
155 modbus_reply_exception(3)
156 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 Data mapping: modbus_mapping_new(3) modbus_mapping_free(3)
163 Receive
165 modbus_receive(3)
166 Reply
168 modbus_reply(3) modbus_reply_exception(3)
169
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 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
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
188 The libmodbus documentation was written by Stéphane Raimbault
189 <stephane.raimbault@gmail.com[1]>
190
192 Main web site: http://www.libmodbus.org/
193 Report bugs on the issue tracker at
195 http://github.com/stephane/libmodbus/issues.
196
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
203 1. stephane.raimbault@gmail.com
204 mailto:stephane.raimbault@gmail.com
205libmodbus 3.0.8 07/31/2019 LIBMODBUS(7)