doc/modbus_set_error_recovery.txt

   1 modbus_set_error_recovery(3)
   2 ============================
   3
   4
   5 NAME
   6 ----
   7 modbus_set_error_recovery - set the error recovery mode
   8
   9
  10 SYNOPSIS
  11 --------
  12 *int modbus_set_error_recovery(modbus_t *'ctx', modbus_error_recovery_mode 'error_recovery');*
  13
  14
  15 DESCRIPTION
  16 -----------
  17 The *modbus_set_error_recovery()* function shall set the error recovery mode to
  18 apply when the connection fails or the byte received is not expected. The
  19 argument _error_recovery_ may be bitwise-or'ed with zero or more of the
  20 following constants.
  21
  22 By default there is no error recovery (`MODBUS_ERROR_RECOVERY_NONE`) so the
  23 application is responsible for controlling the error values returned by
  24 libmodbus functions and for handling them if necessary.
  25
  26 When `MODBUS_ERROR_RECOVERY_LINK` is set, the library will attempt an
  27 reconnection after a delay defined by response timeout of the libmodbus context.
  28 This mode will try an infinite close/connect loop until success on send call and
  29 will just try one time to re-establish the connection on select/read calls (if the
  30 connection was down, the values to read are certainly not available any more after
  31 reconnection, except for slave/server). This mode will also run flush requests
  32 after a delay based on the current response timeout in some situations (eg.
  33 timeout of select call). The reconnection attempt can hang for several seconds
  34 if the network to the remote target unit is down.
  35
  36 When `MODBUS_ERROR_RECOVERY_PROTOCOL` is set, a sleep and flush sequence will be
  37 used to clean up the ongoing communication, this can occurs when the message
  38 length is invalid, the TID is wrong or the received function code is not the
  39 expected one. The response timeout delay will be used to sleep.
  40
  41 The modes are mask values and so they are complementary.
  42
  43 It's not recommended to enable error recovery for slave/server.
  44
  45
  46 RETURN VALUE
  47 ------------
  48 The function shall return 0 if successful. Otherwise it shall return -1 and set
  49 errno to one of the values defined below.
  50
  51
  52 ERRORS
  53 ------
  54 *EINVAL*::
  55 The value of the argument _error_recovery_ is not positive.
  56
  57
  58 EXAMPLE
  59 -------
  60 [source,c]
  61 -------------------
  62 modbus_set_error_recovery(ctx,
  63                           MODBUS_ERROR_RECOVERY_LINK |
  64                           MODBUS_ERROR_RECOVERY_PROTOCOL);
  65 -------------------
  66
  67 AUTHORS
  68 -------
  69 The libmodbus documentation was written by Stéphane Raimbault
  70 <stephane.raimbault@gmail.com>