'\" t
.\" Title: coap_recovery
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 05/14/2022
.\" Manual: libcoap Manual
.\" Source: coap_recovery 4.2.1
.\" Language: English
.\"
.TH "COAP_RECOVERY" "3" "05/14/2022" "coap_recovery 4\&.2\&.1" "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_max_retransmit, coap_session_set_ack_timeout, coap_session_set_ack_random_factor, coap_session_get_max_transmit, coap_session_get_ack_timeout, coap_session_get_ack_random_factor, coap_debug_set_packet_loss \- Work with CoAP packet transmissions
.SH "SYNOPSIS"
.sp
\fB#include \fR
.sp
\fBvoid coap_session_set_max_retransmit(coap_session_t *\fR\fB\fIsession\fR\fR\fB, unsigned int \fR\fB\fIvalue\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
\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
\fBunsigned int coap_session_get_max_transmit(coap_session_t *\fR\fB\fIsession\fR\fR\fB)\fR;
.sp
\fBcoap_fixed_point_t coap_session_get_ack_timeout(coap_session_t *\fR\fB\fIsession\fR\fR\fB)\fR;
.sp
\fBcoap_fixed_point_t coap_session_get_ack_random_factor(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
Link with \fB\-lcoap\-2\fR, \fB\-lcoap\-2\-gnutls\fR, \fB\-lcoap\-2\-openssl\fR or \fB\-lcoap\-2\-tinydtls\fR depending on your (D)TLS library type\&.
.SH "DESCRIPTION"
.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"\&.
.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
Changing the default values for multicast packets is not supported\&.
.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 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_transmit (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\&.
.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
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\&.
.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\&.
.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\&.
.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\&.
.sp
The \fBcoap_session_get_max_retransmit\fR() function returns the current \fIsession\fR maximum retransmit count\&.
.sp
The \fBcoap_session_get_ack_timeout\fR() function returns the current \fIsession\fR initial ack or response timeout\&.
.sp
The \fBcoap_session_get_ack_random_factor\fR() function returns the current \fIsession\fR ack random wait factor\&.
.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 coap_debug_set_packet_loss() is called\&. To remove any packet losses, set the \fIloss_level\fR to "0%"\&.
.SH "RETURN VALUES"
.sp
\fBcoap_session_get_max_retransmit\fR(), \fBcoap_session_get_ack_timeout\fR() and \fBcoap_session_get_ack_random_factor\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 recovery/re\-transmit logic will only work for confirmable requests\&.
.sp
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)\&.
.sp
The client needs to be sending confirmable requests during the test\&.
.sp
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\&.
.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) coap_debug_set_packet_loss("100%") or put in some packet filtering to drop the packets\&.
.sp
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\&.
.SH "FURTHER INFORMATION"
.sp
See "RFC7252: The Constrained Application Protocol (CoAP)" for further information\&.
.SH "BUGS"
.sp
Please report bugs on the mailing list for libcoap: libcoap\-developers@lists\&.sourceforge\&.net
.SH "AUTHORS"
.sp
The libcoap project