'\" t
.\"     Title: coap_recovery
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 10/28/2023
.\"    Manual: libcoap Manual
.\"    Source: coap_recovery 4.3.4
.\"  Language: English
.\"
.TH "COAP_RECOVERY" "3" "10/28/2023" "coap_recovery 4\&.3\&.4" "libcoap Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "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_payloads, coap_session_get_max_payloads, coap_session_set_max_retransmit, coap_session_get_max_retransmit, coap_session_set_non_max_retransmit, coap_session_get_non_max_retransmit, coap_session_set_non_receive_timeout, coap_session_get_non_receive_timeout, coap_session_set_non_timeout, coap_session_get_non_timeout, coap_session_set_nstart, coap_session_get_nstart, coap_session_set_probing_rate, coap_session_get_probing_rate, coap_debug_set_packet_loss \- Work with CoAP packet transmissions 
.SH "SYNOPSIS"
.sp
\fB#include <coap3/coap\&.h>\fR
.sp
\fBvoid coap_session_set_ack_random_factor(coap_session_t *\fR\fB\fIsession\fR\fR\fB, coap_fixed_point_t \fR\fB\fIvalue\fR\fR\fB)\fR;
.sp
\fBcoap_fixed_point_t coap_session_get_ack_random_factor( const coap_session_t *\fR\fB\fIsession\fR\fR\fB)\fR;
.sp
\fBvoid coap_session_set_ack_timeout(coap_session_t *\fR\fB\fIsession\fR\fR\fB, coap_fixed_point_t \fR\fB\fIvalue\fR\fR\fB)\fR;
.sp
\fBcoap_fixed_point_t coap_session_get_ack_timeout( const coap_session_t *\fR\fB\fIsession\fR\fR\fB)\fR;
.sp
\fBvoid coap_session_set_default_leisure(coap_session_t *\fR\fB\fIsession\fR\fR\fB, coap_fixed_point_t \fR\fB\fIvalue\fR\fR\fB)\fR;
.sp
\fBcoap_fixed_point_t coap_session_get_default_leisure( const coap_session_t *\fR\fB\fIsession\fR\fR\fB)\fR;
.sp
\fBvoid coap_session_set_max_payloads(coap_session_t *\fR\fB\fIsession\fR\fR\fB, uint16_t \fR\fB\fIvalue\fR\fR\fB)\fR;
.sp
\fBuint16_t coap_session_get_max_payloads(const coap_session_t *\fR\fB\fIsession\fR\fR\fB)\fR;
.sp
\fBvoid coap_session_set_max_retransmit(coap_session_t *\fR\fB\fIsession\fR\fR\fB, uint16_t \fR\fB\fIvalue\fR\fR\fB)\fR;
.sp
\fBuint16_t coap_session_get_max_retransmit(const coap_session_t *\fR\fB\fIsession\fR\fR\fB)\fR;
.sp
\fBvoid coap_session_set_non_max_retransmit(coap_session_t *\fR\fB\fIsession\fR\fR\fB, uint16_t \fR\fB\fIvalue\fR\fR\fB)\fR;
.sp
\fBuint16_t coap_session_get_non_max_retransmit(const coap_session_t *\fR\fB\fIsession\fR\fR\fB)\fR;
.sp
\fBvoid coap_session_set_non_receive_timeout(coap_session_t *\fR\fB\fIsession\fR\fR\fB, coap_fixed_point_t \fR\fB\fIvalue\fR\fR\fB)\fR;
.sp
\fBcoap_fixed_point_t coap_session_get_non_receive_timeout( const coap_session_t *\fR\fB\fIsession\fR\fR\fB)\fR;
.sp
\fBvoid coap_session_set_non_timeout(coap_session_t *\fR\fB\fIsession\fR\fR\fB, coap_fixed_point_t \fR\fB\fIvalue\fR\fR\fB)\fR;
.sp
\fBcoap_fixed_point_t coap_session_get_non_timeout( const coap_session_t *\fR\fB\fIsession\fR\fR\fB)\fR;
.sp
\fBvoid coap_session_set_nstart(coap_session_t *\fR\fB\fIsession\fR\fR\fB, uint16_t \fR\fB\fIvalue\fR\fR\fB)\fR;
.sp
\fBuint16_t coap_session_get_nstart(const coap_session_t *\fR\fB\fIsession\fR\fR\fB)\fR;
.sp
\fBvoid coap_session_set_probing_rate(coap_session_t *\fR\fB\fIsession\fR\fR\fB, uint32_t \fR\fB\fIvalue\fR\fR\fB)\fR;
.sp
\fBuint32_t coap_session_get_probing_rate(const coap_session_t *\fR\fB\fIsession\fR\fR\fB)\fR;
.sp
\fBint coap_debug_set_packet_loss(const char *\fR\fB\fIloss_level\fR\fR\fB)\fR;
.sp
For specific (D)TLS library support, link with \fB\-lcoap\-3\-notls\fR, \fB\-lcoap\-3\-gnutls\fR, \fB\-lcoap\-3\-openssl\fR, \fB\-lcoap\-3\-mbedtls\fR or \fB\-lcoap\-3\-tinydtls\fR\&. Otherwise, link with \fB\-lcoap\-3\fR to get the default (D)TLS library support\&.
.SH "DESCRIPTION"
.sp
There is CoAP Confirmable message transmission recovery as defined in RFC7252, as well CoAP Non\-Confirmable split into blocks message transmission recovery support as defined in RFC9177\&.
.sp
For CoAP Confirmable messages, it is possible to define the retry counts, repeat rate etc\&. for error recovery\&. Further information can be found in "RFC7272 4\&.2\&. Messages Transmitted Reliably", with the default values defined in "RFC7272 4\&.8\&. Transmission Parameters"\&.
.sp
It is not recommended that the suggested default setting are changed, but there may be some special requirements that need different values and the consequences of changing these values is fully understood\&.
.sp
Some of the parameters or return values are in fixed point format as defined by the coap_fixed_point_t structure as below
.sp
.if n \{\
.RS 4
.\}
.nf
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;
.fi
.if n \{\
.RE
.\}
.sp
The CoAP Confirmable message retry rules are (with the default values to compute the time)
.sp
.if n \{\
.RS 4
.\}
.nf
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
"https://rfc\-editor\&.org/rfc/rfc7252#section\-4\&.8\&.2[RFC7252 4\&.8\&.2\&.
MAX_TRANSMIT_WAIT]"\&.
.fi
.if n \{\
.RE
.\}
.sp
It should be noted that 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\&.
.sp
For CoAP Non\-Confirmable messages with RFC9177 enabled at both ends of a session, it is possible to define the retry counts etc\&. for data recovery\&. Further information can be found in "RFC9177 7\&.2\&. Non\-confirmable (NON)"\&.
.sp
It is also possible to set up packet losses, for both confirmable, and non\-confirmable messages\&. This can be used for stress testing packet transmission recovery as well as application handling of lossy networks\&.
.SH "FUNCTIONS"
.sp
The following functions reflect the RFC7252 and RFC9177 uppercase names in lowercase following the coap_session_set_ or coap_session_get_ function prefix\&.
.sp
\fBFunction: coap_session_set_ack_random_factor()\fR
.sp
The \fBcoap_session_set_ack_random_factor\fR() function updates the \fIsession\fR ack random wait factor, used to randomize re\-transmissions, with the new \fIvalue\fR\&. The default value is 1\&.5 (RFC7252)\&.
.sp
\fBFunction: coap_session_get_ack_random_factor()\fR
.sp
The \fBcoap_session_get_ack_random_factor\fR() function returns the current \fIsession\fR ack random wait factor (RFC7252)\&.
.sp
\fBFunction: coap_session_set_ack_timeout()\fR
.sp
The \fBcoap_session_set_ack_timeout\fR() function updates the \fIsession\fR initial ack or response timeout with the new \fIvalue\fR\&. The default value is 2\&.0 (RFC7252)\&.
.sp
\fBFunction: coap_session_get_ack_timeout()\fR
.sp
The \fBcoap_session_get_ack_timeout\fR() function returns the current \fIsession\fR initial ack or response timeout (RFC7252)\&.
.sp
\fBFunction: coap_session_set_default_leisure()\fR
.sp
The \fBcoap_session_set_default_leisure\fR() function updates the \fIsession\fR default leisure time with the new \fIvalue\fR\&. The default value is 5\&.0 (RFC7252)\&.
.sp
\fBFunction: coap_session_get_default_leisure()\fR
.sp
The \fBcoap_session_get_default_leisure\fR() function returns the current \fIsession\fR default leisure time (RFC7252)\&.
.sp
\fBFunction: coap_session_set_max_payloads()\fR
.sp
The \fBcoap_session_set_max_payloads\fR() function updates the \fIsession\fR maximum payloads count with the new \fIvalue\fR\&. The default value is 10 (RFC9177)\&.
.sp
\fBNOTE:\fR Both ends of the session must have the same maximum payloads value to minimize any recovery times\&.
.sp
\fBFunction: coap_session_get_max_payloads()\fR
.sp
The \fBcoap_session_get_max_payloads\fR() function returns the current \fIsession\fR maximum payloads count (RFC9177)\&.
.sp
\fBFunction: coap_session_set_max_retransmit()\fR
.sp
The \fBcoap_session_set_max_retransmit\fR() function updates the \fIsession\fR maximum retransmit count with the new \fIvalue\fR\&. The default value is 4 (RFC7252)\&.
.sp
\fBFunction: coap_session_get_max_retransmit()\fR
.sp
The \fBcoap_session_get_max_retransmit\fR() function returns the current \fIsession\fR maximum retransmit count (RFC7252)\&.
.sp
\fBFunction: coap_session_set_non_max_retransmit()\fR
.sp
The \fBcoap_session_set_non_max_retransmit\fR() function updates the \fIsession\fR maximum non retransmit count with the new \fIvalue\fR\&. The default value is 4 (RFC9177)\&.
.sp
\fBFunction: coap_session_get_non_max_retransmit()\fR
.sp
The \fBcoap_session_get_non_max_retransmit\fR() function returns the current \fIsession\fR maximum non retransmit count (RFC9177)\&.
.sp
\fBFunction: coap_session_set_non_receive_timeout()\fR
.sp
The \fBcoap_session_set_non_receive_timeout\fR() function updates the \fIsession\fR non receive timeout with the new \fIvalue\fR\&. The default value is 4\&.0 (RFC9177)\&.
.sp
\fBFunction: coap_session_get_non_receive_timeout()\fR
.sp
The \fBcoap_session_get_non_receive_timeout\fR() function returns the current \fIsession\fR non receive timeout (RFC9177)\&.
.sp
\fBFunction: coap_session_set_non_timeout()\fR
.sp
The \fBcoap_session_set_non_timeout\fR() function updates the \fIsession\fR non timeout with the new \fIvalue\fR\&. The default value is 2\&.0 (RFC9177)\&.
.sp
\fBFunction: coap_session_get_non_timeout()\fR
.sp
The \fBcoap_session_get_non_timeout\fR() function returns the current \fIsession\fR non timeout (RFC9177)\&.
.sp
\fBFunction: coap_session_set_nstart()\fR
.sp
The \fBcoap_session_set_nstart\fR() function updates the \fIsession\fR nstart with the new \fIvalue\fR\&. The default value is 1 (RFC7252)\&.
.sp
\fBFunction: coap_session_set_probing_rate()\fR
.sp
The \fBcoap_session_get_nstart\fR() function returns the current \fIsession\fR nstart value (RFC7252)\&.
.sp
\fBFunction: coap_session_set_probing_rate()\fR
.sp
The \fBcoap_session_set_probing_rate\fR() function updates the \fIsession\fR probing rate with the new \fIvalue\fR\&. The default value is 1 byte per second (RFC7252)\&.
.sp
\fBFunction: coap_session_get_probing_rate()\fR
.sp
The \fBcoap_session_get_probing_rate\fR() function returns the current \fIsession\fR probing rate value (RFC7252)\&.
.sp
\fBFunction: coap_debug_set_packet_loss()\fR
.sp
The \fBcoap_debug_set_packet_loss\fR() function is uses to set the packet loss levels as defined in \fIloss_level\fR\&. \fIloss_level\fR can be set as a percentage from "0%" to "100%"\&. Alternatively, it is 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 \fBcoap_debug_set_packet_loss\fR() is called\&. To remove any packet losses, set the \fIloss_level\fR to "0%"\&.
.SH "RETURN VALUES"
.sp
\fBcoap_session_get_ack_random_factor\fR(), \fBcoap_session_get_ack_timeout\fR(), \fBcoap_session_get_default_leisure\fR(), \fBcoap_session_get_max_payloads\fR(), \fBcoap_session_get_max_retransmit\fR(), \fBcoap_session_get_non_max_retransmit\fR(), \fBcoap_session_get_non_receive_timeout\fR(), \fBcoap_session_get_non_timeout\fR(), \fBcoap_session_get_nstart\fR() and \fBcoap_session_get_probing_rate\fR() return their respective current values\&.
.sp
\fBcoap_debug_set_packet_loss\fR() returns 0 if \fIloss_level\fR does not parse correctly, otherwise 1 if successful\&.
.SH "TESTING"
.sp
The libcoap RFC7252 recovery/re\-transmit logic will only work for confirmable requests or if RFC9177 support is enabled for non\-confirmable large body transmissions that need to span multiple packets\&.
.sp
To see what is happening (other than by sniffing the network traffic), the logging level needs to be set to COAP_LOG_DEBUG in the client by using \fBcoap_set_log_level\fR(COAP_LOG_DEBUG) and \fBcoap_dtls_set_log_level\fR(COAP_LOG_DEBUG)\&.
.sp
The server can either be stopped, or if packet loss levels are set to 100% by using \fBcoap_debug_set_packet_loss\fR("100%") when receiving the client requests\&.
.sp
\fBNOTE:\fR 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) \fBcoap_debug_set_packet_loss\fR("100%") or put in some packet filtering to drop the packets\&.
.sp
For confirmable transmissions, the client should then restart transmitting the requests based on the ack_timeout, ack_random_factor and max_retransmit values\&. The client\(cqs nack_handler will get called with COAP_NACK_TOO_MANY_RETRIES when the confirmable request cannot be successfully transmitted\&.
.sp
For non\-confirmable block transmissions (RFC9177 enabled), the client should then restart transmitting the missing requests based on the max_payloads, non_timeout, non_receive_timeout, and non_max_retransmit values\&. The client\(cqs nack_handler will get called with COAP_NACK_TOO_MANY_RETRIES when the non\-confirmable large body request cannot be successfully transmitted\&.
.SH "FURTHER INFORMATION"
.sp
See
.sp
"RFC7252: The Constrained Application Protocol (CoAP)"
.sp
"RFC9177: Constrained Application Protocol (CoAP) Block\-Wise Transfer Options Supporting Robust Transmission"
.sp
for further information\&.
.SH "BUGS"
.sp
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
.SH "AUTHORS"
.sp
The libcoap project <libcoap\-developers@lists\&.sourceforge\&.net>