Update documentation of modbus_set_error_recovery

Stéphane Raimbault
1 parent d1f18543
Showing 3 changed files with 40 additions and 17 deletions
NEWS
doc/modbus_set_error_recovery.txt
src/modbus.h
-libmodbus 2.9.4 (2011-05-XX)
+libmodbus 2.9.4 (2011-06-XX)
 ============================
 - IPv6 support
@@ -20,6 +20,8 @@ libmodbus 2.9.4 (2011-05-XX)
     * modbus_set_timeout_end -> modbus_set_byte_timeout
 - New functions modbus_set/get_serial_mode by Manfred Gruber and Stéphane
   Raimbault for RS485 communications
+- Improved recovery mode (see modbus_set_error_recovery documentation) for
+  data link and protocol errors.
 libmodbus 2.9.3 (2011-01-14)
 ============================
@@ -9,39 +9,60 @@ modbus_set_error_recovery - set the error recovery mode
 SYNOPSIS
 --------
-*int modbus_set_error_recovery(modbus_t *'ctx', int 'enabled');*
+*int modbus_set_error_recovery(modbus_t *'ctx',
+                               modbus_error_recovery_mode 'error_recovery');*
 DESCRIPTION
 -----------
 The _modbus_set_error_recovery()_ function shall set the error recovery mode to
-apply when the connection fails.
+apply when the connection fails or the date received are not expected.
-By default there is no error recovery so the application must check the error
-values returned by libmodbus functions and handle them if necessary.
+By default there is no error recovery ('MODBUS_ERROR_RECOVERY_NONE') so the
+application is responsible for controlling the error values returned by
+libmodbus functions and for handling them if necessary.
-When enabled, the library will attempt an immediate reconnection which may hang
-for several seconds if the network to the remote target unit is down. The write
-will try a infinite close/connect loop until to be successful and the
-select/read calls will just try to retablish the connection one time then will
-return an error (if the connecton was down, the values to read are certainly not
-available anymore after reconnection, except for slave/server).
+When 'MODBUS_ERROR_RECOVERY_LINK' is set, the library will attempt an immediate
+reconnection (which may hang for several seconds if the network to the remote
+target unit is down). This mode will try a infinite close/connect loop until
+success on send call and will just try one time to retablish the connection on
+select/read calls (if the connecton was down, the values to read are certainly
+not available anymore after reconnection, except for slave/server). This mode
+will also run flush requests after a delay based on the current response timeout
+in some situations (eg. timeout of select call).
-It's not recommanded to enable error recovery for slave/server.
+When 'MODBUS_ERROR_RECOVERY_PROTOCOL' is set, a sleep and flush sequence will be
+used to cleanup the ongoing communication, this can occurs when the message
+length is invalid, the TID is wrong or the received function code is not the
+expected one.
+
+The modes are mask values and so they are complementary.
+
+It's not recommended to enable error recovery for slave/server.
 RETURN VALUE
 ------------
-The _modbus_close()_ function shall return 0 if successful. Otherwise it shall
-return -1 and set errno to one of the values defined below.
+The _modbus_set_error_recovery()_ function shall return 0 if
+successful. Otherwise it shall return -1 and set errno to one of the values
+defined below.
 ERRORS
 ------
 *EINVAL*::
-The value of the argument 'enabled' is not 'TRUE' of 'FALSE'.
+The value of the argument 'error_recovery' is not positive.
+EXAMPLE
+-------
+[source,c]
+-------------------
+modbus_set_error_recovery(ctx,
+                          MODBUS_ERROR_RECOVERY_LINK |
+                          MODBUS_ERROR_RECOVERY_PROTOCOL);
+-------------------
+
 AUTHORS
 -------
 The libmodbus documentation was written by Stéphane Raimbault
@@ -139,10 +139,10 @@ typedef enum
     MODBUS_ERROR_RECOVERY_NONE          = 0,
     MODBUS_ERROR_RECOVERY_LINK          = (1<<1),
     MODBUS_ERROR_RECOVERY_PROTOCOL      = (1<<2),
-} modbus_error_recovery_type;
+} modbus_error_recovery_mode;
 int modbus_set_slave(modbus_t* ctx, int slave);
-int modbus_set_error_recovery(modbus_t *ctx, modbus_error_recovery_type error_recovery);
+int modbus_set_error_recovery(modbus_t *ctx, modbus_error_recovery_mode error_recovery);
 void modbus_set_socket(modbus_t *ctx, int socket);
 int modbus_get_socket(modbus_t *ctx);