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_ack_random_factor, 15coap_session_get_ack_random_factor, 16coap_session_set_ack_timeout, 17coap_session_get_ack_timeout, 18coap_session_set_default_leisure, 19coap_session_get_default_leisure, 20coap_session_set_max_payloads, 21coap_session_get_max_payloads, 22coap_session_set_max_retransmit, 23coap_session_get_max_retransmit, 24coap_session_set_non_max_retransmit, 25coap_session_get_non_max_retransmit, 26coap_session_set_non_receive_timeout, 27coap_session_get_non_receive_timeout, 28coap_session_set_non_timeout, 29coap_session_get_non_timeout, 30coap_session_set_nstart, 31coap_session_get_nstart, 32coap_session_set_probing_rate, 33coap_session_get_probing_rate, 34coap_debug_set_packet_loss 35- Work with CoAP packet transmissions 36 37SYNOPSIS 38-------- 39*#include <coap@LIBCOAP_API_VERSION@/coap.h>* 40 41*void coap_session_set_ack_random_factor(coap_session_t *_session_, 42coap_fixed_point_t _value_)*; 43 44*coap_fixed_point_t coap_session_get_ack_random_factor( 45const coap_session_t *_session_)*; 46 47*void coap_session_set_ack_timeout(coap_session_t *_session_, 48coap_fixed_point_t _value_)*; 49 50*coap_fixed_point_t coap_session_get_ack_timeout( 51const coap_session_t *_session_)*; 52 53*void coap_session_set_default_leisure(coap_session_t *_session_, 54coap_fixed_point_t _value_)*; 55 56*coap_fixed_point_t coap_session_get_default_leisure( 57const coap_session_t *_session_)*; 58 59*void coap_session_set_max_payloads(coap_session_t *_session_, 60uint16_t _value_)*; 61 62*uint16_t coap_session_get_max_payloads(const coap_session_t *_session_)*; 63 64*void coap_session_set_max_retransmit(coap_session_t *_session_, 65uint16_t _value_)*; 66 67*uint16_t coap_session_get_max_retransmit(const coap_session_t *_session_)*; 68 69*void coap_session_set_non_max_retransmit(coap_session_t *_session_, 70uint16_t _value_)*; 71 72*uint16_t coap_session_get_non_max_retransmit(const coap_session_t *_session_)*; 73 74*void coap_session_set_non_receive_timeout(coap_session_t *_session_, 75coap_fixed_point_t _value_)*; 76 77*coap_fixed_point_t coap_session_get_non_receive_timeout( 78const coap_session_t *_session_)*; 79 80*void coap_session_set_non_timeout(coap_session_t *_session_, 81coap_fixed_point_t _value_)*; 82 83*coap_fixed_point_t coap_session_get_non_timeout( 84const coap_session_t *_session_)*; 85 86*void coap_session_set_nstart(coap_session_t *_session_, uint16_t _value_)*; 87 88*uint16_t coap_session_get_nstart(const coap_session_t *_session_)*; 89 90*void coap_session_set_probing_rate(coap_session_t *_session_, 91uint32_t _value_)*; 92 93*uint32_t coap_session_get_probing_rate(const coap_session_t *_session_)*; 94 95*int coap_debug_set_packet_loss(const char *_loss_level_)*; 96 97For specific (D)TLS library support, link with 98*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, 99*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* 100or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*. Otherwise, link with 101*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support. 102 103DESCRIPTION 104----------- 105There is CoAP Confirmable message transmission recovery as defined in 106https://rfc-editor.org/rfc/rfc7252[RFC7252], as well CoAP Non-Confirmable 107split into blocks message transmission recovery support as defined in 108https://rfc-editor.org/rfc/rfc9177[RFC9177]. 109 110For CoAP Confirmable messages, it is possible to define the retry counts, 111repeat rate etc. for error recovery. Further information can be found in 112"https://rfc-editor.org/rfc/rfc7252#section-4.2[RFC7272 4.2. Messages 113Transmitted Reliably]", 114with the default values defined in 115"https://rfc-editor.org/rfc/rfc7252#section-4.8[RFC7272 4.8. Transmission 116Parameters]". 117 118It is not recommended that the suggested default setting are changed, but 119there may be some special requirements that need different values and the 120consequences of changing these values is fully understood. 121 122Some of the parameters or return values are in fixed point format as defined 123by the coap_fixed_point_t structure as below 124---- 125typedef struct coap_fixed_point_t { 126 uint16_t integer_part; /* Integer part of fixed point variable */ 127 uint16_t fractional_part; /* Fractional part of fixed point variable 128 1/1000 (3 points) precision */ 129} coap_fixed_point_t; 130---- 131 132The CoAP Confirmable message retry rules are (with the default values to 133compute the time) 134---- 1351st retransmit after 1 * ack_timeout * ack_random factor (3 seconds) 1362nd retransmit after 2 * ack_timeout * ack_random factor (6 seconds) 1373rd retransmit after 3 * ack_timeout * ack_random factor (12 seconds) 1384th retransmit after 4 * ack_timeout * ack_random factor (24 seconds) 1395th retransmit after 5 * ack_timeout * ack_random factor (48 seconds) 140 141As max_retransmit (by default) is 4, then the 5th retransmit does not get sent, 142but at that point COAP_NACK_TOO_MANY_RETRIES gets raised in the nack_handler 143(if defined). Note that the sum of the seconds is 93 matching 144"https://rfc-editor.org/rfc/rfc7252#section-4.8.2[RFC7252 4.8.2. 145MAX_TRANSMIT_WAIT]". 146---- 147 148It should be noted that these retries are separate from the DTLS or TLS 149encrypted session setup retry timeouts. For DTLS, the initial requesting 150packet will get sent max_retransmit times before reporting failure. 151For TLS the initial TCP connection will timeout before reporting failure. 152 153For CoAP Non-Confirmable messages with 154https://rfc-editor.org/rfc/rfc9177[RFC9177] enabled at both ends of a 155session, it is possible to define the retry counts etc. for data recovery. 156Further information can be found in 157"https://rfc-editor.org/rfc/rfc9177#section-7.2[RFC9177 1587.2. Non-confirmable (NON)]". 159 160It is also possible to set up packet losses, for both confirmable, and 161non-confirmable messages. This can be used for stress testing packet 162transmission recovery as well as application handling of lossy networks. 163 164FUNCTIONS 165--------- 166 167The following functions reflect the https://rfc-editor.org/rfc/rfc7252[RFC7252] 168and https://rfc-editor.org/rfc/rfc9177[RFC9177] uppercase names 169in lowercase following the coap_session_set_ or coap_session_get_ function 170prefix. 171 172*Function: coap_session_set_ack_random_factor()* 173 174The *coap_session_set_ack_random_factor*() function updates the _session_ ack 175random wait factor, used to randomize re-transmissions, with the new _value_. 176The default value is 1.5 (RFC7252). 177 178*Function: coap_session_get_ack_random_factor()* 179 180The *coap_session_get_ack_random_factor*() function returns the current 181_session_ ack random wait factor (RFC7252). 182 183*Function: coap_session_set_ack_timeout()* 184 185The *coap_session_set_ack_timeout*() function updates the _session_ initial 186ack or response timeout with the new _value_. The default value is 2.0 187(RFC7252). 188 189*Function: coap_session_get_ack_timeout()* 190 191The *coap_session_get_ack_timeout*() function returns the current _session_ 192initial ack or response timeout (RFC7252). 193 194*Function: coap_session_set_default_leisure()* 195 196The *coap_session_set_default_leisure*() function updates the _session_ 197default leisure time with the new _value_. The default value is 5.0 (RFC7252). 198 199*Function: coap_session_get_default_leisure()* 200 201The *coap_session_get_default_leisure*() function returns the current _session_ 202default leisure time (RFC7252). 203 204*Function: coap_session_set_max_payloads()* 205 206The *coap_session_set_max_payloads*() function updates the _session_ maximum 207payloads count with the new _value_. The default value is 10 (RFC9177). 208 209*NOTE:* Both ends of the session must have the same maximum payloads value to 210minimize any recovery times. 211 212*Function: coap_session_get_max_payloads()* 213 214The *coap_session_get_max_payloads*() function returns the current _session_ 215maximum payloads count (RFC9177). 216 217*Function: coap_session_set_max_retransmit()* 218 219The *coap_session_set_max_retransmit*() function updates the _session_ maximum 220retransmit count with the new _value_. The default value is 4 (RFC7252). 221 222*Function: coap_session_get_max_retransmit()* 223 224The *coap_session_get_max_retransmit*() function returns the current _session_ 225maximum retransmit count (RFC7252). 226 227*Function: coap_session_set_non_max_retransmit()* 228 229The *coap_session_set_non_max_retransmit*() function updates the _session_ 230maximum non retransmit count with the new _value_. The default value is 4 231(RFC9177). 232 233*Function: coap_session_get_non_max_retransmit()* 234 235The *coap_session_get_non_max_retransmit*() function returns the current 236_session_ maximum non retransmit count (RFC9177). 237 238*Function: coap_session_set_non_receive_timeout()* 239 240The *coap_session_set_non_receive_timeout*() function updates the _session_ 241non receive timeout with the new _value_. The default value is 4.0 242(RFC9177). 243 244*Function: coap_session_get_non_receive_timeout()* 245 246The *coap_session_get_non_receive_timeout*() function returns the current 247_session_ non receive timeout (RFC9177). 248 249*Function: coap_session_set_non_timeout()* 250 251The *coap_session_set_non_timeout*() function updates the _session_ 252non timeout with the new _value_. The default value is 2.0 253(RFC9177). 254 255*Function: coap_session_get_non_timeout()* 256 257The *coap_session_get_non_timeout*() function returns the current 258_session_ non timeout (RFC9177). 259 260*Function: coap_session_set_nstart()* 261 262The *coap_session_set_nstart*() function updates the _session_ nstart 263with the new _value_. The default value is 1 (RFC7252). 264 265*Function: coap_session_set_probing_rate()* 266 267The *coap_session_get_nstart*() function returns the current _session_ 268nstart value (RFC7252). 269 270*Function: coap_session_set_probing_rate()* 271 272The *coap_session_set_probing_rate*() function updates the _session_ probing 273rate with the new _value_. The default value is 1 byte per second (RFC7252). 274 275*Function: coap_session_get_probing_rate()* 276 277The *coap_session_get_probing_rate*() function returns the current _session_ 278probing rate value (RFC7252). 279 280*Function: coap_debug_set_packet_loss()* 281 282The *coap_debug_set_packet_loss*() function is uses to set the packet loss 283levels as defined in _loss_level_. _loss_level_ can be set as a percentage 284from "0%" to "100%". 285Alternatively, it is possible to specify which packets of a packet sequence 286are dropped. A definition of "1,5-9,11-20,101" means that packets 1, 5 287through 9, 11 through 20 and 101 will get dropped. A maximum of 10 different 288packet sets is supported. The packet count is reset to 0 when 289*coap_debug_set_packet_loss*() is called. 290To remove any packet losses, set the _loss_level_ to "0%". 291 292RETURN VALUES 293------------- 294*coap_session_get_ack_random_factor*(), *coap_session_get_ack_timeout*(), 295*coap_session_get_default_leisure*(), *coap_session_get_max_payloads*(), 296*coap_session_get_max_retransmit*(), *coap_session_get_non_max_retransmit*(), 297*coap_session_get_non_receive_timeout*(), *coap_session_get_non_timeout*(), 298*coap_session_get_nstart*() and *coap_session_get_probing_rate*() return their 299respective current values. 300 301*coap_debug_set_packet_loss*() returns 0 if _loss_level_ does not parse 302correctly, otherwise 1 if successful. 303 304TESTING 305------- 306 307The libcoap RFC7252 recovery/re-transmit logic will only work for confirmable 308requests or if RFC9177 support is enabled for non-confirmable large body 309transmissions that need to span multiple packets. 310 311To see what is happening (other than by sniffing the network traffic), the 312logging level needs to be set to COAP_LOG_DEBUG in the client by using 313*coap_set_log_level*(COAP_LOG_DEBUG) and 314*coap_dtls_set_log_level*(COAP_LOG_DEBUG). 315 316The server can either be stopped, or if packet loss levels are set to 100% by 317using *coap_debug_set_packet_loss*("100%") when receiving the client requests. 318 319*NOTE:* If the server end of the connection is returning ICMP unreachable 320packets after being turned off, you will get a debug message of the form 321"coap_network_read: unreachable", so libcoap will stop doing the retries. If 322this is the case, then you need to make use of (on the server) 323*coap_debug_set_packet_loss*("100%") or put in some packet filtering to drop the 324packets. 325 326For confirmable transmissions, the client should then restart transmitting the 327requests based on the ack_timeout, ack_random_factor and max_retransmit values. 328The client's nack_handler will get called with COAP_NACK_TOO_MANY_RETRIES when 329the confirmable request cannot be successfully transmitted. 330 331For non-confirmable block transmissions (RFC9177 enabled), the client should 332then restart transmitting the missing requests based on the max_payloads, 333non_timeout, non_receive_timeout, and non_max_retransmit values. The client's 334nack_handler will get called with COAP_NACK_TOO_MANY_RETRIES when 335the non-confirmable large body request cannot be successfully transmitted. 336 337 338FURTHER INFORMATION 339------------------- 340See 341 342"https://rfc-editor.org/rfc/rfc7252[RFC7252: The Constrained Application Protocol (CoAP)]" 343 344"https://rfc-editor.org/rfc/rfc9177[RFC9177: Constrained Application Protocol (CoAP) Block-Wise Transfer Options Supporting Robust Transmission]" 345 346for further information. 347 348BUGS 349---- 350Please report bugs on the mailing list for libcoap: 351libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 352https://github.com/obgm/libcoap/issues 353 354AUTHORS 355------- 356The libcoap project <libcoap-developers@lists.sourceforge.net> 357