doc/libmodbus.txt

   1 libmodbus(7)
   2 ============
   3
   4
   5 NAME
   6 ----
   7 libmodbus - a fast and portable Modbus library
   8
   9
  10 SYNOPSIS
  11 --------
  12 *#include <modbus.h>*
  13
  14 *cc* \`pkg-config --cflags --libs libmodbus` 'files'
  15
  16
  17 DESCRIPTION
  18 -----------
  19 libmodbus is a library to send/receive data with a device which respects the
  20 Modbus protocol. This library contains various backends to communicate over
  21 different networks (eg. serial in RTU mode or Ethernet in TCP/IPv6). The
  22 http://www.modbus.org site provides documentation about the protocol at
  23 http://www.modbus.org/specs.php.
  24
  25 libmodbus provides an abstraction of the lower communication layers and offers
  26 the same API on all supported platforms.
  27
  28 This documentation presents an overview of libmodbus concepts, describes how
  29 libmodbus abstracts Modbus communication with different hardware and platforms
  30 and provides a reference manual for the functions provided by the libmodbus
  31 library.
  32
  33
  34 Contexts
  35 ~~~~~~~~
  36 The Modbus protocol contains many variants (eg. serial RTU or Ehternet TCP), to
  37 ease the implementation of a variant, the library was designed to use a backend
  38 for each variant. The backends are also a convenient way to fulfill other
  39 requirements (eg. real-time operations). Each backend offers a specific function
  40 to create a new 'modbus_t' context. The 'modbus_t' context is an opaque
  41 structure containing all necessary information to establish a connection with
  42 others Modbus devices according to the selected variant.
  43
  44 You can choose the best context for your needs among:
  45
  46 RTU Context
  47 ^^^^^^^^^^^
  48 The RTU backend (Remote Terminal Unit) is used in serial communication and makes
  49 use of a compact, binary representation of the data for protocol
  50 communication. The RTU format follows the commands/data with a cyclic redundancy
  51 check checksum as an error check mechanism to ensure the reliability of
  52 data. Modbus RTU is the most common implementation available for Modbus. A
  53 Modbus RTU message must be transmitted continuously without inter-character
  54 hesitations (extract from Wikipedia, Modbus, http://en.wikipedia.org/wiki/Modbus
  55 (as of Mar. 13, 2011, 20:51 GMT).
  56
  57 The Modbus RTU framing calls a slave, a device/service which handle Modbus
  58 requests, and a master, a client which send requests. The communication is
  59 always initiated by the master.
  60
  61 Many Modbus devices can be connected together on the same physical link so
  62 before sending a message, you must set the slave (receiver) with
  63 linkmb:modbus_set_slave[3]. If you're running a slave, its slave number will be
  64 used to filter received messages.
  65
  66 The libmodbus implementation of RTU isn't time based as stated in original
  67 Modbus specification, instead all bytes are sent as fast as possible and a
  68 response or an indication is considered complete when all expected characters
  69 have been received. This implementation offers very fast communication but you
  70 must take care to set a response timeout of slaves less than response timeout of
  71 master (ortherwise other slaves may ignore master requests when one of the slave
  72 is not responding).
  73
  74 Create a Modbus RTU context::
  75     linkmb:modbus_new_rtu[3]
  76
  77
  78 Set the serial mode::
  79     linkmb:modbus_rtu_get_serial_mode[3]
  80     linkmb:modbus_rtu_set_serial_mode[3]
  81     linkmb:modbus_rtu_get_rts[3]
  82     linkmb:modbus_rtu_set_rts[3]
  83     linkmb:modbus_rtu_set_custom_rts[3]
  84     linkmb:modbus_rtu_get_rts_delay[3]
  85     linkmb:modbus_rtu_set_rts_delay[3]
  86
  87
  88 TCP (IPv4) Context
  89 ^^^^^^^^^^^^^^^^^^
  90 The TCP backend implements a Modbus variant used for communications over
  91 TCP/IPv4 networks. It does not require a checksum calculation as lower layer
  92 takes care of the same.
  93
  94 Create a Modbus TCP context::
  95     linkmb:modbus_new_tcp[3]
  96
  97
  98 TCP PI (IPv4 and IPv6) Context
  99 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 100 The TCP PI (Protocol Independent) backend implements a Modbus variant used for
 101 communications over TCP IPv4 and IPv6 networks. It does not require a checksum
 102 calculation as lower layer takes care of the same.
 103
 104 Contrary to the TCP IPv4 only backend, the TCP PI backend offers hostname
 105 resolution but it consumes about 1Kb of additional memory.
 106
 107 Create a Modbus TCP context::
 108     linkmb:modbus_new_tcp_pi[3]
 109
 110
 111 Common
 112 ^^^^^^
 113 Before using any libmodbus functions, the caller must allocate and initialize a
 114 'modbus_t' context with functions explained above, then the following functions
 115 are provided to modify and free a 'context':
 116
 117 Free libmodbus context::
 118     linkmb:modbus_free[3]
 119
 120 Set slave ID::
 121     linkmb:modbus_set_slave[3]
 122
 123 Enable debug mode::
 124     linkmb:modbus_set_debug[3]
 125
 126 Timeout settings::
 127     linkmb:modbus_get_byte_timeout[3]
 128     linkmb:modbus_set_byte_timeout[3]
 129     linkmb:modbus_get_response_timeout[3]
 130     linkmb:modbus_set_response_timeout[3]
 131
 132 Error recovery mode::
 133     linkmb:modbus_set_error_recovery[3]
 134
 135 Setter/getter of internal socket::
 136     linkmb:modbus_set_socket[3]
 137     linkmb:modbus_get_socket[3]
 138
 139 Information about header::
 140     linkmb:modbus_get_header_length[3]
 141
 142 Macros for data manipulation::
 143
 144 - MODBUS_GET_HIGH_BYTE(data), extracts the high byte from a byte
 145 - MODBUS_GET_LOW_BYTE(data), extracts the low byte from a byte
 146 - MODBUS_GET_INT64_FROM_INT16(tab_int16, index), builds an int64 from the four
 147   first int16 starting at tab_int16[index]
 148 - MODBUS_GET_INT32_FROM_INT16(tab_int16, index), builds an int32 from the two
 149   first int16 starting at tab_int16[index]
 150 - MODBUS_GET_INT16_FROM_INT8(tab_int8, index), builds an int16 from the two
 151   first int8 starting at tab_int8[index]
 152 - MODBUS_SET_INT16_TO_INT8(tab_int8, index, value), set an int16 value into
 153   the two first bytes starting at tab_int8[index]
 154 - MODBUS_SET_INT32_TO_INT16(tab_int16, index, value), set an int32 value into
 155   the two first int16 starting at tab_int16[index]
 156 - MODBUS_SET_INT64_TO_INT16(tab_int16, index, value), set an int64 value into
 157   the four first int16 starting at tab_int16[index]
 158
 159 Handling of bits and bytes::
 160     linkmb:modbus_set_bits_from_byte[3]
 161     linkmb:modbus_set_bits_from_bytes[3]
 162     linkmb:modbus_get_byte_from_bits[3]
 163
 164 Set or get float numbers::
 165     linkmb:modbus_get_float_abcd[3]
 166     linkmb:modbus_set_float_abcd[3]
 167     linkmb:modbus_get_float_badc[3]
 168     linkmb:modbus_set_float_badc[3]
 169     linkmb:modbus_get_float_cdab[3]
 170     linkmb:modbus_set_float_cdab[3]
 171     linkmb:modbus_get_float_dcba[3]
 172     linkmb:modbus_set_float_dcba[3]
 173     linkmb:modbus_get_float[3] (deprecated)
 174     linkmb:modbus_set_float[3] (deprecated)
 175
 176
 177
 178 Connection
 179 ~~~~~~~~~~
 180 The following functions are provided to establish and close a connection with
 181 Modbus devices:
 182
 183 Establish a connection::
 184     linkmb:modbus_connect[3]
 185
 186 Close a connection::
 187     linkmb:modbus_close[3]
 188
 189 Flush a connection::
 190     linkmb:modbus_flush[3]
 191
 192
 193 Client
 194 ~~~~~~
 195 The Modbus protocol defines different data types and functions to read and write
 196 them from/to remote devices. The following functions are used by the clients to
 197 send Modbus requests:
 198
 199 Read data::
 200      linkmb:modbus_read_bits[3]
 201      linkmb:modbus_read_input_bits[3]
 202      linkmb:modbus_read_registers[3]
 203      linkmb:modbus_read_input_registers[3]
 204      linkmb:modbus_report_slave_id[3]
 205
 206 Write data::
 207      linkmb:modbus_write_bit[3]
 208      linkmb:modbus_write_register[3]
 209      linkmb:modbus_write_bits[3]
 210      linkmb:modbus_write_registers[3]
 211
 212 Write and read data::
 213       linkmb:modbus_write_and_read_registers[3]
 214
 215 Raw requests::
 216     linkmb:modbus_send_raw_request[3]
 217     linkmb:modbus_receive_confirmation[3]
 218
 219 Reply an exception::
 220     linkmb:modbus_reply_exception[3]
 221
 222
 223 Server
 224 ~~~~~~
 225 The server is waiting for request from clients and must answer when it is
 226 concerned by the request.
 227
 228 In TCP mode, you must not use the usual linkmb:modbus_connect[3] to establish the connection but a pair of accept/listen calls::
 229      linkmb:modbus_tcp_listen[3]
 230      linkmb:modbus_tcp_accept[3]
 231      linkmb:modbus_tcp_pi_listen[3]
 232      linkmb:modbus_tcp_pi_accept[3]
 233
 234 then the data can be received with::
 235      linkmb:modbus_receive[3]
 236
 237 and a response can be send with::
 238      linkmb:modbus_reply[3]
 239      linkmb:modbus_reply_exception[3]
 240
 241 To handle the mapping of your Modbus data, you must use:
 242      linkmb:modbus_mapping_new[3]
 243      linkmb:modbus_mapping_free[3]
 244
 245
 246 ERROR HANDLING
 247 --------------
 248 The libmodbus functions handle errors using the standard conventions found on
 249 POSIX systems. Generally, this means that upon failure a libmodbus function
 250 shall return either a NULL value (if returning a pointer) or a negative value
 251 (if returning an integer), and the actual error code shall be stored in the
 252 'errno' variable.
 253
 254 The *modbus_strerror()* function is provided to translate libmodbus-specific
 255 error codes into error message strings; for details refer to
 256 linkmb:modbus_strerror[3].
 257
 258
 259 MISCELLANEOUS
 260 -------------
 261 The _LIBMODBUS_VERSION_STRING_ constant indicates the libmodbus version the
 262 program has been compiled against. The variables 'libmodbus_version_major',
 263 'libmodbus_version_minor', 'libmodbus_version_micro' give the version the
 264 program is linked against.
 265
 266
 267 AUTHORS
 268 -------
 269 The libmodbus documentation was written by Stéphane Raimbault
 270 <stephane.raimbault@gmail.com>
 271
 272
 273 RESOURCES
 274 ---------
 275 Main web site: <http://www.libmodbus.org/>
 276
 277 Report bugs on the issue tracker at
 278 <http://github.com/stephane/libmodbus/issues>.
 279
 280
 281 COPYING
 282 -------
 283 Free use of this software is granted under the terms of the GNU Lesser General
 284 Public License (LGPL v2.1+). For details see the file `COPYING.LESSER` included
 285 with the libmodbus distribution.