COAP_RECOVERY(3)

📦 version 4.3.1, in debian bookworm

COAP_RECOVERY 💖 (libcoap manual, section 3)

okay bestie, sit down, hydrate, because we're about to talk about CoAP packet transmissions and how libcoap handles retries, timeouts, and deliberately ✨losing✨ packets for science. this is the coap_recovery page, and yes it covers a whole little friend group of functions. let's get into it 🫶

✨ NAME ✨

coap_recovery, coap_session_set_ack_random_factor, coap_session_get_ack_random_factor, coap_session_set_ack_timeout, coap_session_get_ack_timeout, coap_session_set_default_leisure, coap_session_get_default_leisure, coap_session_set_max_retransmit, coap_session_get_max_retransmit, coap_session_set_nstart, coap_session_get_nstart, coap_session_set_probing_wait, coap_session_get_probing_wait, coap_debug_set_packet_loss — work with CoAP packet transmissions 🦋

✨ SYNOPSIS ✨

#include <coap3/coap.h>

void coap_session_set_ack_random_factor(coap_session_t *session, coap_fixed_point_t value);

coap_fixed_point_t coap_session_get_ack_random_factor(const coap_session_t *session);

void coap_session_set_ack_timeout(coap_session_t *session, coap_fixed_point_t value);

coap_fixed_point_t coap_session_get_ack_timeout(const coap_session_t *session);

void coap_session_set_default_leisure(coap_session_t *session, coap_fixed_point_t value);

coap_fixed_point_t coap_session_get_default_leisure(const coap_session_t *session);

void coap_session_set_max_retransmit(coap_session_t *session, uint16_t value);

uint16_t coap_session_get_max_retransmit(const coap_session_t *session);

void coap_session_set_nstart(coap_session_t *session, uint16_t value);

uint16_t coap_session_get_nstart(const coap_session_t *session);

void coap_session_set_probing_rate(coap_session_t *session, uint32_t value);

uint32_t coap_session_get_probing_rate(const coap_session_t *session);

int coap_debug_set_packet_loss(const char *loss_level);

and now the linking tea ☕ — for specific (D)TLS library support, link with -lcoap-3-notls, -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or -lcoap-3-tinydtls. otherwise, link with -lcoap-3 to get the default (D)TLS library support. pick your fighter 💅

✨ DESCRIPTION ✨

so for CoAP Confirmable messages, you can define the retry counts, the repeat rate, etc., for error recovery. more info lives in "RFC7272: 4.2. Messages Transmitted Reliably", and the default values are defined in "RFC7272: 4.8 Transmission Parameters". 📚

not recommended that you change the suggested default settings!! like, lowkey don't. but there may be some special requirements that need different values — and only if the consequences of changing these values are fully understood. no cap. 🙈

some of the parameters and return values are in fixed point format, defined by the coap_fixed_point_t structure, like this:

typedef struct coap_fixed_point_t {
  uint16_t integer_part;    /* Integer part of fixed point variable */
  uint16_t fractional_part; /* Fractional part of fixed point variable
                               1/1000 (3 points) precision */
} coap_fixed_point_t;

and here's the retry schedule, with the default values plugged in to compute the time ⏰:

1st retransmit after 1 * ack_timeout * ack_random factor (3 seconds)
2nd retransmit after 2 * ack_timeout * ack_random factor (6 seconds)
3rd retransmit after 3 * ack_timeout * ack_random factor (12 seconds)
4th retransmit after 4 * ack_timeout * ack_random factor (24 seconds)
5th retransmit after 5 * ack_timeout * ack_random factor (48 seconds)

As max_retransmit (by default) is 4, then the 5th retransmit does not get sent,
but at that point COAP_NACK_TOO_MANY_RETRIES gets raised in the nack_handler
(if defined). Note that the sum of the seconds is 93 matching RFC7252.

quick heads up bestie: these retries are separate from the DTLS or TLS encrypted session setup retry timeouts. for DTLS, the initial requesting packet will get sent max_retransmit times before reporting failure. for TLS, the initial TCP connection will timeout before reporting failure. two different clocks, two different dramas 🕰️

it's also possible to set up packet losses, for both confirmable and non-confirmable messages. iconic for stress testing packet transmission recovery, and also for application handling of lossy networks. 🔥

the following functions reflect the RFC7252 uppercase names in lowercase, following the coap_session[sg]_ function prefix.

  • coap_session_set_ack_random_factor() — updates the session ack random wait factor (the thing that randomizes re-transmissions) with the new value. the default value is 1.5.
  • coap_session_get_ack_random_factor() — returns the current session ack random wait factor.
  • coap_session_set_ack_timeout() — updates the session initial ack or response timeout with the new value. the default value is 2.0.
  • coap_session_get_ack_timeout() — returns the current session initial ack or response timeout.
  • coap_session_set_default_leisure() — updates the session default leisure time with the new value. the initial default value is 5.0.
  • coap_session_get_default_leisure() — returns the current session default leisure time.
  • coap_session_set_max_retransmit() — updates the session maximum retransmit count with the new value. the default value is 4.
  • coap_session_get_max_retransmit() — returns the current session maximum retransmit count.
  • coap_session_set_nstart() — updates the session nstart with the new value. the default value is 1.
  • coap_session_get_nstart() — returns the current session nstart value.
  • coap_session_set_probing_rate() — updates the session probing rate with the new value. the default value is 1 byte per second.
  • coap_session_get_probing_rate() — returns the current session probing rate value.
  • coap_debug_set_packet_loss() — used to set the packet loss levels as defined in loss_level. 💀 loss_level can be set as a percentage from "0%" to "100%". alternatively, it's possible to specify which packets of a packet sequence are dropped. a definition of "1,5-9,11-20,101" means that packets 1, 5 through 9, 11 through 20 and 101 will get dropped. a maximum of 10 different packet sets is supported. the packet count is reset to 0 when coap_debug_set_packet_loss() is called. to remove any packet losses, set the loss_level to "0%".

✨ RETURN VALUES ✨

coap_session_get_ack_random_factor(), coap_session_get_ack_timeout(), coap_session_get_default_leisure(), coap_session_get_max_retransmit(), coap_session_get_nstart() and coap_session_get_probing_rate() return their respective current values. 🎁

coap_debug_set_packet_loss() returns 0 if loss_level does not parse correctly, otherwise 1 if successful. slay.

✨ TESTING ✨

the libcoap recovery/re-transmit logic will only work for confirmable requests. periodt.

to see what is happening (other than by sniffing the network traffic 👀), the logging level needs to be set to LOG_DEBUG in the client by using coap_set_log_level(LOG_DEBUG) and coap_dtls_set_log_level(LOG_DEBUG).

the client needs to be sending confirmable requests during the test.

the server can either be stopped, or — if packet loss levels are set to 100% by using coap_debug_set_packet_loss("100%") — when receiving the client requests.

NOTE: if the server end of the connection is returning ICMP unreachable packets after being turned off, you will get a debug message of the form "coap_network_read: unreachable", so libcoap will stop doing the retries. 😭 if this is the case, then you need to make use of (on the server) coap_debug_set_packet_loss("100%") or put in some packet filtering to drop the packets.

the client should then restart transmitting the requests based on the ack_timeout, ack_random_factor and max_retransmit values. the client's nack_handler will get called with COAP_NACK_TOO_MANY_RETRIES when the confirmable request cannot be successfully transmitted. 💅

✨ FURTHER INFORMATION ✨

see "RFC7252: The Constrained Application Protocol (CoAP)" for further information. 🦋

✨ BUGS ✨

please report bugs on the mailing list for libcoap: libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at https://github.com/obgm/libcoap/issues 🐛🫶

✨ AUTHORS ✨

The libcoap project <libcoap-developers@lists.sourceforge.net> 👑

and that's the whole page bestie!! this was coap_recovery version 4.3.1, dated 11/28/2022 — literally iconic behavior from the libcoap girlies. go forth and set your ack_timeout responsibly 💖✨🎀🦋🌸

📦 where this page comes from