Peter M. Groen / libmodbus

Commit 3b09d0f4b1070eb53e06dd0645102fc19841def1

Authored by Stéphane Raimbault
1 parent d1f18543

Update documentation of modbus_set_error_recovery

Inline Side-by-side
Showing 3 changed files with 40 additions and 17 deletions
1   -libmodbus 2.9.4 (2011-05-XX)
  1 +libmodbus 2.9.4 (2011-06-XX)
2 2 ============================
3 3  
4 4 - IPv6 support
... ... @@ -20,6 +20,8 @@ libmodbus 2.9.4 (2011-05-XX)
20 20 * modbus_set_timeout_end -> modbus_set_byte_timeout
21 21 - New functions modbus_set/get_serial_mode by Manfred Gruber and Stéphane
22 22 Raimbault for RS485 communications
  23 +- Improved recovery mode (see modbus_set_error_recovery documentation) for
  24 + data link and protocol errors.
23 25  
24 26 libmodbus 2.9.3 (2011-01-14)
25 27 ============================
... ...
doc/modbus_set_error_recovery.txt
  View file @3b09d0f
... ... @@ -9,39 +9,60 @@ modbus_set_error_recovery - set the error recovery mode
9 9  
10 10 SYNOPSIS
11 11 --------
12   -*int modbus_set_error_recovery(modbus_t *'ctx', int 'enabled');*
  12 +*int modbus_set_error_recovery(modbus_t *'ctx',
  13 + modbus_error_recovery_mode 'error_recovery');*
13 14  
14 15  
15 16 DESCRIPTION
16 17 -----------
17 18 The _modbus_set_error_recovery()_ function shall set the error recovery mode to
18   -apply when the connection fails.
  19 +apply when the connection fails or the date received are not expected.
19 20  
20   -By default there is no error recovery so the application must check the error
21   -values returned by libmodbus functions and handle them if necessary.
  21 +By default there is no error recovery ('MODBUS_ERROR_RECOVERY_NONE') so the
  22 +application is responsible for controlling the error values returned by
  23 +libmodbus functions and for handling them if necessary.
22 24  
23   -When enabled, the library will attempt an immediate reconnection which may hang
24   -for several seconds if the network to the remote target unit is down. The write
25   -will try a infinite close/connect loop until to be successful and the
26   -select/read calls will just try to retablish the connection one time then will
27   -return an error (if the connecton was down, the values to read are certainly not
28   -available anymore after reconnection, except for slave/server).
  25 +When 'MODBUS_ERROR_RECOVERY_LINK' is set, the library will attempt an immediate
  26 +reconnection (which may hang for several seconds if the network to the remote
  27 +target unit is down). This mode will try a infinite close/connect loop until
  28 +success on send call and will just try one time to retablish the connection on
  29 +select/read calls (if the connecton was down, the values to read are certainly
  30 +not available anymore after reconnection, except for slave/server). This mode
  31 +will also run flush requests after a delay based on the current response timeout
  32 +in some situations (eg. timeout of select call).
29 33  
30   -It's not recommanded to enable error recovery for slave/server.
  34 +When 'MODBUS_ERROR_RECOVERY_PROTOCOL' is set, a sleep and flush sequence will be
  35 +used to cleanup the ongoing communication, this can occurs when the message
  36 +length is invalid, the TID is wrong or the received function code is not the
  37 +expected one.
  38 +
  39 +The modes are mask values and so they are complementary.
  40 +
  41 +It's not recommended to enable error recovery for slave/server.
31 42  
32 43  
33 44 RETURN VALUE
34 45 ------------
35   -The _modbus_close()_ function shall return 0 if successful. Otherwise it shall
36   -return -1 and set errno to one of the values defined below.
  46 +The _modbus_set_error_recovery()_ function shall return 0 if
  47 +successful. Otherwise it shall return -1 and set errno to one of the values
  48 +defined below.
37 49  
38 50  
39 51 ERRORS
40 52 ------
41 53 *EINVAL*::
42   -The value of the argument 'enabled' is not 'TRUE' of 'FALSE'.
  54 +The value of the argument 'error_recovery' is not positive.
43 55  
44 56  
  57 +EXAMPLE
  58 +-------
  59 +[source,c]
  60 +-------------------
  61 +modbus_set_error_recovery(ctx,
  62 + MODBUS_ERROR_RECOVERY_LINK |
  63 + MODBUS_ERROR_RECOVERY_PROTOCOL);
  64 +-------------------
  65 +
45 66 AUTHORS
46 67 -------
47 68 The libmodbus documentation was written by Stéphane Raimbault
... ...
src/modbus.h
  View file @3b09d0f
... ... @@ -139,10 +139,10 @@ typedef enum
139 139 MODBUS_ERROR_RECOVERY_NONE = 0,
140 140 MODBUS_ERROR_RECOVERY_LINK = (1<<1),
141 141 MODBUS_ERROR_RECOVERY_PROTOCOL = (1<<2),
142   -} modbus_error_recovery_type;
  142 +} modbus_error_recovery_mode;
143 143  
144 144 int modbus_set_slave(modbus_t* ctx, int slave);
145   -int modbus_set_error_recovery(modbus_t *ctx, modbus_error_recovery_type error_recovery);
  145 +int modbus_set_error_recovery(modbus_t *ctx, modbus_error_recovery_mode error_recovery);
146 146 void modbus_set_socket(modbus_t *ctx, int socket);
147 147 int modbus_get_socket(modbus_t *ctx);
148 148  
... ...