1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc,tw=0: 3 4coap_recovery(3) 5================= 6:doctype: manpage 7:man source: coap_recovery 8:man version: @PACKAGE_VERSION@ 9:man manual: libcoap Manual 10 11NAME 12---- 13coap_recovery, 14coap_session_set_max_retransmit, 15coap_session_set_ack_timeout, 16coap_session_set_ack_random_factor, 17coap_session_get_max_retransmit, 18coap_session_get_ack_timeout, 19coap_session_get_ack_random_factor, 20coap_debug_set_packet_loss 21- Work with CoAP packet transmissions 22 23SYNOPSIS 24-------- 25*#include <coap@LIBCOAP_API_VERSION@/coap.h>* 26 27*void coap_session_set_max_retransmit(coap_session_t *_session_, 28unsigned int _value_)*; 29 30*void coap_session_set_ack_timeout(coap_session_t *_session_, 31coap_fixed_point_t _value_)*; 32 33*void coap_session_set_ack_random_factor(coap_session_t *_session_, 34coap_fixed_point_t _value_)*; 35 36*unsigned int coap_session_get_max_retransmit(const coap_session_t *_session_)*; 37 38*coap_fixed_point_t coap_session_get_ack_timeout( 39const coap_session_t *_session_)*; 40 41*coap_fixed_point_t coap_session_get_ack_random_factor( 42const coap_session_t *_session_)*; 43 44*int coap_debug_set_packet_loss(const char *_loss_level_)*; 45 46For specific (D)TLS library support, link with 47*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, 48*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* 49or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*. Otherwise, link with 50*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support. 51 52DESCRIPTION 53----------- 54For CoAP Confirmable messages, it is possible to define the retry counts, 55repeat rate etc. for error recovery. Further information can be found in 56"RFC7272: 4.2. Messages Transmitted Reliably". 57 58It is not recommended that the suggested default setting are changed, but 59there may be some special requirements that need different values and the 60consequences of changing these values is fully understood. 61 62Changing the default values for multicast packets is not supported. 63 64Some of the parameters or return values are in fixed point format as defined 65by the coap_fixed_point_t structure as below 66---- 67typedef struct coap_fixed_point_t { 68 uint16_t integer_part; /* Integer part of fixed point variable */ 69 uint16_t fractional_part; /* Fractional part of fixed point variable 70 1/1000 (3 points) precision */ 71} coap_fixed_point_t; 72---- 73 74The CoAP message retry rules are (with the default values to compute the time) 75---- 761st retransmit after 1 * ack_timeout * ack_random factor (3 seconds) 772nd retransmit after 2 * ack_timeout * ack_random factor (6 seconds) 783rd retransmit after 3 * ack_timeout * ack_random factor (12 seconds) 794th retransmit after 4 * ack_timeout * ack_random factor (24 seconds) 805th retransmit after 5 * ack_timeout * ack_random factor (48 seconds) 81 82As max_retransmit (by default) is 4, then the 5th retransmit does not get sent, 83but at that point COAP_NACK_TOO_MANY_RETRIES gets raised in the nack_handler 84(if defined). Note that the sum of the seconds is 93 matching RFC7252. 85---- 86 87It should be noted that these retries are separate from the DTLS or TLS 88encrypted session setup retry timeouts. For DTLS, the initial requesting 89packet will get sent max_retransmit times before reporting failure. 90For TLS the initial TCP connection will timeout before reporting failure. 91 92It is also possible to set up packet losses, for both confirmable, and 93non-confirmable messages. This can be used for stress testing packet 94transmission recovery as well as application handling of lossy networks. 95 96The *coap_session_set_max_retransmit*() function updates the _session_ maximum 97retransmit count with the new _value_. The default value is 4. 98 99The *coap_session_set_ack_timeout*() function updates the _session_ initial 100ack or response timeout with the new _value_. The default value is 2.0. 101 102The *coap_session_set_ack_random_factor*() function updates the _session_ ack 103random wait factor, used to randomize re-transmissions, with the new _value_. 104The default value is 1.5. 105 106The *coap_session_get_max_retransmit*() function returns the current _session_ 107maximum retransmit count. 108 109The *coap_session_get_ack_timeout*() function returns the current _session_ 110initial ack or response timeout. 111 112The *coap_session_get_ack_random_factor*() function returns the current 113_session_ ack random wait factor. 114 115The *coap_debug_set_packet_loss*() function is uses to set the packet loss 116levels as defined in _loss_level_. _loss_level_ can be set as a percentage 117from "0%" to "100%". 118Alternatively, it is possible to specify which packets of a packet sequence 119are dropped. A definition of "1,5-9,11-20,101" means that packets 1, 5 120through 9, 11 through 20 and 101 will get dropped. A maximum of 10 different 121packet sets is supported. The packet count is reset to 0 when 122coap_debug_set_packet_loss() is called. 123To remove any packet losses, set the _loss_level_ to "0%". 124 125RETURN VALUES 126------------- 127*coap_session_get_max_retransmit*(), *coap_session_get_ack_timeout*() and 128*coap_session_get_ack_random_factor*() return their respective current values. 129 130*coap_debug_set_packet_loss*() returns 0 if _loss_level_ does not parse 131correctly, otherwise 1 if successful. 132 133TESTING 134------- 135 136The libcoap recovery/re-transmit logic will only work for confirmable requests. 137 138To see what is happening (other than by sniffing the network traffic), the 139logging level needs to be set to LOG_DEBUG in the client by using 140coap_set_log_level(LOG_DEBUG) and coap_dtls_set_log_level(LOG_DEBUG). 141 142The client needs to be sending confirmable requests during the test. 143 144The server can either be stopped, or if packet loss levels are set to 100% by 145using coap_debug_set_packet_loss("100%") when receiving the client requests. 146 147*NOTE:* If the server end of the connection is returning ICMP unreachable packets 148after being turned off, you will get a debug message of the form 149"coap_network_read: unreachable", so libcoap will stop doing the retries. If 150this is the case, then you need to make use of (on the server) 151coap_debug_set_packet_loss("100%") or put in some packet filtering to drop the 152packets. 153 154The client should then restart transmitting the requests based on the 155ack_timeout, ack_random_factor and max_retransmit values. The client's 156nack_handler will get called with COAP_NACK_TOO_MANY_RETRIES when the 157confirmable request cannot be successfully transmitted. 158 159 160FURTHER INFORMATION 161------------------- 162See "RFC7252: The Constrained Application Protocol (CoAP)" for further 163information. 164 165BUGS 166---- 167Please report bugs on the mailing list for libcoap: 168libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 169https://github.com/obgm/libcoap/issues 170 171AUTHORS 172------- 173The libcoap project <libcoap-developers@lists.sourceforge.net> 174