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
  84
  85
  86 TCP (IPv4) Context
  87 ^^^^^^^^^^^^^^^^^^
  88 The TCP backend implements a Modbus variant used for communications over
  89 TCP/IPv4 networks. It does not require a checksum calculation as lower layer
  90 takes care of the same.
  91
  92 Create a Modbus TCP context::
  93     linkmb:modbus_new_tcp[3]
  94
  95
  96 TCP PI (IPv4 and IPv6) Context
  97 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  98 The TCP PI (Protocol Indepedent) backend implements a Modbus variant used for
  99 communications over TCP IPv4 and IPv6 networks. It does not require a checksum
 100 calculation as lower layer takes care of the same.
 101
 102 Contrary to the TCP IPv4 only backend, the TCP PI backend offers hostname
 103 resolution but it consumes about 1Kb of additional memory.
 104
 105 Create a Modbus TCP context::
 106     linkmb:modbus_new_tcp_pi[3]
 107
 108
 109 Common
 110 ^^^^^^
 111 Before using any libmodbus functions, the caller must allocate and initialize a
 112 'modbus_t' context with functions explained above, then the following functions
 113 are provided to modify and free a 'context':
 114
 115 Free libmodbus context::
 116     linkmb:modbus_free[3]
 117
 118 Set slave ID::
 119     linkmb:modbus_set_slave[3]
 120
 121 Enable debug mode::
 122     linkmb:modbus_set_debug[3]
 123
 124 Timeout settings::
 125     linkmb:modbus_get_byte_timeout[3]
 126     linkmb:modbus_set_byte_timeout[3]
 127     linkmb:modbus_get_response_timeout[3]
 128     linkmb:modbus_set_response_timeout[3]
 129
 130 Error recovery mode::
 131     linkmb:modbus_set_error_recovery[3]
 132
 133 Setter/getter of internal socket::
 134     linkmb:modbus_set_socket[3]
 135     linkmb:modbus_get_socket[3]
 136
 137 Information about header::
 138     linkmb:modbus_get_header_length[3]
 139
 140 A libmodbus 'context' is thread safe and may be shared among as many application
 141 threads as necessary, without any additional locking required on the part of the
 142 caller.
 143
 144 Macros for data manipulation::
 145
 146 - MODBUS_GET_HIGH_BYTE(data), extracts the high byte from a byte
 147 - MODBUS_GET_LOW_BYTE(data), extracts the low byte from a byte
 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
 155 Handling of bits and bytes::
 156     linkmb:modbus_set_bits_from_byte[3]
 157     linkmb:modbus_set_bits_from_bytes[3]
 158     linkmb:modbus_get_byte_from_bits[3]
 159
 160 Set or get float numbers::
 161     linkmb:modbus_get_float[3]
 162     linkmb:modbus_set_float[3]
 163     linkmb:modbus_get_float_dcba[3]
 164     linkmb:modbus_set_float_dcba[3]
 165
 166
 167 Connection
 168 ~~~~~~~~~~
 169 The following functions are provided to establish and close a connection with
 170 Modbus devices:
 171
 172 Establish a connection::
 173     linkmb:modbus_connect[3]
 174
 175 Close a connection::
 176     linkmb:modbus_close[3]
 177
 178 Flush a connection::
 179     linkmb:modbus_flush[3]
 180
 181
 182 Client
 183 ~~~~~~
 184 The Modbus protocol defines different data types and functions to read and write
 185 them from/to remote devices. The following functions are used by the clients to
 186 send Modbus requests:
 187
 188 Read data::
 189      linkmb:modbus_read_bits[3]
 190      linkmb:modbus_read_input_bits[3]
 191      linkmb:modbus_read_registers[3]
 192      linkmb:modbus_read_input_registers[3]
 193      linkmb:modbus_report_slave_id[3]
 194
 195 Write data::
 196      linkmb:modbus_write_bit[3]
 197      linkmb:modbus_write_register[3]
 198      linkmb:modbus_write_bits[3]
 199      linkmb:modbus_write_registers[3]
 200
 201 Write and read data::
 202       linkmb:modbus_write_and_read_registers[3]
 203
 204 Raw requests::
 205     linkmb:modbus_send_raw_request[3]
 206     linkmb:modbus_receive_confirmation[3]
 207
 208 Reply an exception::
 209     linkmb:modbus_reply_exception[3]
 210
 211
 212 Server
 213 ~~~~~~
 214 The server is waiting for request from clients and must answer when it is
 215 concerned by the request. The libmodbus offers the following functions to
 216 handle requests:
 217
 218 Data mapping:
 219      linkmb:modbus_mapping_new[3]
 220      linkmb:modbus_mapping_free[3]
 221
 222 Receive::
 223      linkmb:modbus_receive[3]
 224
 225 Reply::
 226      linkmb:modbus_reply[3]
 227      linkmb:modbus_reply_exception[3]
 228
 229
 230 ERROR HANDLING
 231 --------------
 232 The libmodbus functions handle errors using the standard conventions found on
 233 POSIX systems. Generally, this means that upon failure a libmodbus function
 234 shall return either a NULL value (if returning a pointer) or a negative value
 235 (if returning an integer), and the actual error code shall be stored in the
 236 'errno' variable.
 237
 238 The *modbus_strerror()* function is provided to translate libmodbus-specific
 239 error codes into error message strings; for details refer to
 240 linkmb:modbus_strerror[3].
 241
 242
 243 MISCELLANEOUS
 244 -------------
 245 The _LIBMODBUS_VERSION_STRING_ constant indicates the libmodbus version the
 246 program has been compiled against. The variables 'libmodbus_version_major',
 247 'libmodbus_version_minor', 'libmodbus_version_micro' give the version the
 248 program is linked against.
 249
 250
 251 AUTHORS
 252 -------
 253 The libmodbus documentation was written by Stéphane Raimbault
 254 <stephane.raimbault@gmail.com>
 255
 256
 257 RESOURCES
 258 ---------
 259 Main web site: <http://www.libmodbus.org/>
 260
 261 Report bugs on the issue tracker at
 262 <http://github.com/stephane/libmodbus/issues>.
 263
 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.