docs/index.md

   1 # libmodbus
   2
   3 A featureful and portable Open Source Modbus library.
   4
   5 ## Description
   6
   7 libmodbus is a library to send/receive data with a device which respects the
   8 Modbus protocol. This library contains various backends to communicate over
   9 different networks (eg. serial in RTU mode or Ethernet in TCP IPv4/IPv6). The
  10 <http://www.modbus.org> site provides documentation about the [Modbus
  11 Specifications and Implementation Guides](http://www.modbus.org/specs.php).
  12
  13 libmodbus provides an abstraction of the lower communication layers and offers
  14 the same API on all supported platforms.
  15
  16 This documentation presents an overview of libmodbus concepts, describes how
  17 libmodbus abstracts Modbus communication with different hardware and platforms
  18 and provides a reference manual for the functions provided by the libmodbus
  19 library.
  20
  21 ## Use cases
  22
  23 The library can be used to write a:
  24
  25 - **client**, the application reads/writes data from various devices.
  26 - **server**, the application provides data to several clients.
  27
  28 <figure markdown>
  29   <img src="assets/client-sensors.webp" width="512">
  30   <figcaption>A libmodbus client that reads only the temperatures from sensors.</figcaption>
  31 </figure>
  32
  33 <figure markdown>
  34   <img src="assets/server-grafana.webp" width="512">
  35   <figcaption>A libmodbus server that exposes data to a Grafana service.</figcaption>
  36 </figure>
  37
  38 ## Contexts
  39
  40 The Modbus protocol supports several transport protocols (eg. serial RTU,
  41 Ethernet TCP) called backends in *libmodbus*.
  42
  43 The first step is to allocate and set a `modbus_t` context according to the
  44 required backend (RTU or TCP) with a dedicated function, such as
  45 [modbus_new_rtu](modbus_new_rtu.md).
  46 The function will return an opaque structure called `modbus_t` containing all
  47 necessary information to establish a connection with other Modbus devices
  48 according to the selected backend.
  49
  50 Once this context has been created, you can use use the common API provided by
  51 *libmodbus* to read/write or set the various timeouts. With this common API,
  52 it's easy to switch the backend of your application from RTU to TCP IPv6 for
  53 example.
  54
  55 ### RTU Context
  56
  57 The RTU backend (Remote Terminal Unit) is used in serial communication and makes
  58 use of a compact, binary representation of the data for protocol communication.
  59 The RTU format follows the commands/data with a cyclic redundancy check checksum
  60 as an error check mechanism to ensure the reliability of data. Modbus RTU is the
  61 most common implementation available for Modbus. A Modbus RTU message must be
  62 transmitted continuously without inter-character hesitations (extract from
  63 Wikipedia, [Modbus](http://en.wikipedia.org/wiki/Modbus) as of Mar. 13, 2011,
  64 20:51 GMT).
  65
  66 The Modbus RTU framing calls a slave, a device/service which handle Modbus
  67 requests, and a master, a client which send requests. The communication is
  68 always initiated by the master.
  69
  70 Many Modbus devices can be connected together on the same physical link so
  71 before sending a message, you must set the slave (receiver) with
  72 [modbus_set_slave](modbus_set_slave.md). If you're running a slave, its slave number
  73 will be used to filter received messages.
  74
  75 The libmodbus implementation of RTU isn't time based as stated in original
  76 Modbus specification, instead all bytes are sent as fast as possible and a
  77 response or an indication is considered complete when all expected characters
  78 have been received. This implementation offers very fast communication but you
  79 must take care to set a response timeout of slaves less than response timeout of
  80 master (otherwise other slaves may ignore master requests when one of the slaves
  81 is not responding).
  82
  83 To create a Modbus RTU context, you should use [modbus_new_rtu](modbus_new_rtu.md).
  84
  85 You can tweak the serial mode with the following functions:
  86
  87 - [modbus_rtu_get_serial_mode](modbus_rtu_get_serial_mode.md)
  88 - [modbus_rtu_set_serial_mode](modbus_rtu_set_serial_mode.md)
  89 - [modbus_rtu_get_rts](modbus_rtu_get_rts.md)
  90 - [modbus_rtu_set_rts](modbus_rtu_set_rts.md)
  91 - [modbus_rtu_set_custom_rts](modbus_rtu_set_custom_rts.md)
  92 - [modbus_rtu_get_rts_delay](modbus_rtu_get_rts_delay.md)
  93 - [modbus_rtu_set_rts_delay](modbus_rtu_set_rts_delay.md)
  94
  95 ### TCP (IPv4) Context
  96
  97 The TCP backend implements a Modbus variant used for communications over
  98 TCP/IPv4 networks. It does not require a checksum calculation as lower layer
  99 takes care of the same.
 100
 101 To create a Modbus TCP context, you should use [modbus_new_tcp](modbus_new_tcp.md).
 102
 103 ### TCP PI (IPv4 and IPv6) Context
 104
 105 The TCP PI (Protocol Independent) backend implements a Modbus variant used for
 106 communications over TCP IPv4 and IPv6 networks. It does not require a checksum
 107 calculation as lower layer takes care of the same.
 108
 109 Contrary to the TCP IPv4 only backend, the TCP PI backend offers hostname
 110 resolution but it consumes about 1 kB of additional memory.
 111
 112 Create a Modbus TCP PI context, you should use [modbus_new_tcp_pi](modbus_new_tcp_pi.md).
 113
 114 ## Connection
 115
 116 The following functions are provided to establish and close a connection with
 117 Modbus devices:
 118
 119 - [modbus_connect](modbus_connect.md) establishes a connection.
 120 - [modbus_close](modbus_close.md) closes a connection.
 121 - [modbus_flush](modbus_flush.md) flushed a connection.
 122
 123 In RTU, you should define the slave ID of your client with
 124 [modbus_set_slave](modbus_set_slave.md).
 125
 126 To analyse the exchanged data, you can enable the debug mode with
 127 [modbus_set_debug](modbus_set_debug.md).
 128
 129 Once you have completed the communication or at the end of your program, you
 130 should free the resources with the common function, [modbus_free](modbus_free.md)
 131
 132 ## Reads and writes from the client
 133
 134 The Modbus protocol defines different data types and functions to read and write
 135 them from/to remote devices. The following functions are used by the clients to
 136 send Modbus requests:
 137
 138 To read data:
 139
 140 - [modbus_read_bits](modbus_read_bits.md)
 141 - [modbus_read_input_bits](modbus_read_input_bits.md)
 142 - [modbus_read_registers](modbus_read_registers.md)
 143 - [modbus_read_input_registers](modbus_read_input_registers.md)
 144 - [modbus_report_slave_id](modbus_report_slave_id.md)
 145
 146 To write data:
 147
 148 - [modbus_write_bit](modbus_write_bit.md)
 149 - [modbus_write_register](modbus_write_register.md)
 150 - [modbus_write_bits](modbus_write_bits.md)
 151 - [modbus_write_registers](modbus_write_registers.md)
 152
 153 To write and read data in a single operation:
 154
 155 - [modbus_write_and_read_registers](modbus_write_and_read_registers.md)
 156
 157 To send and receive low-level requests:
 158
 159 - [modbus_send_raw_request](modbus_send_raw_request.md)
 160 - [modbus_send_raw_request_tid](modbus_send_raw_request_tid.md)
 161 - [modbus_receive_confirmation](modbus_receive_confirmation.md)
 162
 163 To reply to an exception:
 164
 165 - [modbus_reply_exception](modbus_reply_exception.md)
 166
 167 ## Handling requests from server
 168
 169 The server is waiting for request from clients and must answer when it is
 170 concerned by the request. The libmodbus offers the following functions to
 171 handle requests:
 172
 173 Data mapping:
 174
 175 - [modbus_mapping_new](modbus_mapping_new.md)
 176 - [modbus_mapping_free](modbus_mapping_free.md)
 177
 178 Receive:
 179
 180 - [modbus_receive](modbus_receive.md)
 181
 182 Reply:
 183
 184 - [modbus_reply](modbus_reply.md)
 185 - [modbus_reply_exception](modbus_reply_exception.md)
 186
 187 ## Advanced functions
 188
 189 Timeout settings:
 190
 191 - [modbus_get_byte_timeout](modbus_get_byte_timeout.md)
 192 - [modbus_set_byte_timeout](modbus_set_byte_timeout.md)
 193 - [modbus_get_response_timeout](modbus_get_response_timeout.md)
 194 - [modbus_set_response_timeout](modbus_set_response_timeout.md)
 195
 196 Error recovery mode:
 197
 198 - [modbus_set_error_recovery](modbus_set_error_recovery.md)
 199
 200 Setter/getter of internal socket:
 201
 202 - [modbus_set_socket](modbus_set_socket.md)
 203 - [modbus_get_socket](modbus_get_socket.md)
 204
 205 Information about header:
 206
 207 - [modbus_get_header_length](modbus_get_header_length.md)
 208
 209 ## Data handling
 210
 211 Macros for data manipulation:
 212
 213 - `MODBUS_GET_HIGH_BYTE(data)`, extracts the high byte from a byte
 214 - `MODBUS_GET_LOW_BYTE(data)`, extracts the low byte from a byte
 215 - `MODBUS_GET_INT64_FROM_INT16(tab_int16, index)`, builds an int64 from the four first int16 starting at tab_int16[index]
 216 - `MODBUS_GET_INT32_FROM_INT16(tab_int16, index)`, builds an int32 from the two first int16 starting at tab_int16[index]
 217 - `MODBUS_GET_INT16_FROM_INT8(tab_int8, index)`, builds an int16 from the two first int8 starting at tab_int8[index]
 218 - `MODBUS_SET_INT16_TO_INT8(tab_int8, index, value)`, set an int16 value into the two first bytes starting at tab_int8[index]
 219 - `MODBUS_SET_INT32_TO_INT16(tab_int16, index, value)`, set an int32 value into the two first int16 starting at tab_int16[index]
 220 - `MODBUS_SET_INT64_TO_INT16(tab_int16, index, value)`, set an int64 value into the four first int16 starting at tab_int16[index]
 221
 222 Handling of bits and bytes:
 223
 224 - [modbus_set_bits_from_byte](modbus_set_bits_from_byte.md)
 225 - [modbus_set_bits_from_bytes](modbus_set_bits_from_bytes.md)
 226 - [modbus_get_byte_from_bits](modbus_get_byte_from_bits.md)
 227
 228 Set or get float numbers:
 229
 230 - [modbus_get_float_abcd](modbus_get_float_abcd.md)
 231 - [modbus_set_float_abcd](modbus_set_float_abcd.md)
 232 - [modbus_get_float_badc](modbus_get_float_badc.md)
 233 - [modbus_set_float_badc](modbus_set_float_badc.md)
 234 - [modbus_get_float_cdab](modbus_get_float_cdab.md)
 235 - [modbus_set_float_cdab](modbus_set_float_cdab.md)
 236 - [modbus_get_float_dcba](modbus_get_float_dcba.md)
 237 - [modbus_set_float_dcba](modbus_set_float_dcba.md)
 238 - [modbus_get_float](modbus_get_float.md) **deprecated**
 239 - [modbus_set_float](modbus_set_float.md) **deprecated**
 240
 241 ## Error handling
 242
 243 The libmodbus functions handle errors using the standard conventions found on
 244 POSIX systems. Generally, this means that upon failure a libmodbus function
 245 shall return either a NULL value (if returning a pointer) or a negative value
 246 (if returning an integer), and the actual error code shall be stored in the
 247 `errno` variable.
 248
 249 The *modbus_strerror()* function is provided to translate libmodbus-specific
 250 error codes into error message strings; for details refer to
 251 [modbus_strerror](modbus_strerror.md).
 252
 253 ## Miscellaneous
 254
 255 To deviate from the Modbus standard, you can enable or disable quirks with:
 256
 257 - [modbus_disable_quirks](modbus_disable_quirks.md)
 258 - [modbus_enable_quirks](modbus_enable_quirks.md)
 259
 260 The `_LIBMODBUS_VERSION_STRING_` constant indicates the libmodbus version the
 261 program has been compiled against. The variables 'libmodbus_version_major',
 262 'libmodbus_version_minor', 'libmodbus_version_micro' give the version the
 263 program is linked against.
 264
 265 ## Copying
 266
 267 Free use of this software is granted under the terms of the GNU Lesser General
 268 Public License (LGPL v2.1+). For details see the file `COPYING.LESSER` included
 269 with the libmodbus distribution.