1COAP_RECOVERY(3)                libcoap Manual                COAP_RECOVERY(3)
2
3
4

NAME

6       coap_recovery, coap_session_set_max_retransmit,
7       coap_session_set_ack_timeout, coap_session_set_ack_random_factor,
8       coap_session_get_max_retransmit, coap_session_get_ack_timeout,
9       coap_session_get_ack_random_factor, coap_debug_set_packet_loss - Work
10       with CoAP packet transmissions
11

SYNOPSIS

13       #include <coap3/coap.h>
14
15       void coap_session_set_max_retransmit(coap_session_t *session, unsigned
16       int value);
17
18       void coap_session_set_ack_timeout(coap_session_t *session,
19       coap_fixed_point_t value);
20
21       void coap_session_set_ack_random_factor(coap_session_t *session,
22       coap_fixed_point_t value);
23
24       unsigned int coap_session_get_max_retransmit(const coap_session_t
25       *session);
26
27       coap_fixed_point_t coap_session_get_ack_timeout( const coap_session_t
28       *session);
29
30       coap_fixed_point_t coap_session_get_ack_random_factor( const
31       coap_session_t *session);
32
33       int coap_debug_set_packet_loss(const char *loss_level);
34
35       For specific (D)TLS library support, link with -lcoap-3-notls,
36       -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
37       -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
38       (D)TLS library support.
39

DESCRIPTION

41       For CoAP Confirmable messages, it is possible to define the retry
42       counts, repeat rate etc. for error recovery. Further information can be
43       found in "RFC7272: 4.2. Messages Transmitted Reliably".
44
45       It is not recommended that the suggested default setting are changed,
46       but there may be some special requirements that need different values
47       and the consequences of changing these values is fully understood.
48
49       Changing the default values for multicast packets is not supported.
50
51       Some of the parameters or return values are in fixed point format as
52       defined by the coap_fixed_point_t structure as below
53
54           typedef struct coap_fixed_point_t {
55             uint16_t integer_part;    /* Integer part of fixed point variable */
56             uint16_t fractional_part; /* Fractional part of fixed point variable
57                                          1/1000 (3 points) precision */
58           } coap_fixed_point_t;
59
60       The CoAP message retry rules are (with the default values to compute
61       the time)
62
63           1st retransmit after 1 * ack_timeout * ack_random factor (3 seconds)
64           2nd retransmit after 2 * ack_timeout * ack_random factor (6 seconds)
65           3rd retransmit after 3 * ack_timeout * ack_random factor (12 seconds)
66           4th retransmit after 4 * ack_timeout * ack_random factor (24 seconds)
67           5th retransmit after 5 * ack_timeout * ack_random factor (48 seconds)
68
69           As max_retransmit (by default) is 4, then the 5th retransmit does not get sent,
70           but at that point COAP_NACK_TOO_MANY_RETRIES gets raised in the nack_handler
71           (if defined). Note that the sum of the seconds is 93 matching RFC7252.
72
73       It should be noted that these retries are separate from the DTLS or TLS
74       encrypted session setup retry timeouts. For DTLS, the initial
75       requesting packet will get sent max_retransmit times before reporting
76       failure. For TLS the initial TCP connection will timeout before
77       reporting failure.
78
79       It is also possible to set up packet losses, for both confirmable, and
80       non-confirmable messages. This can be used for stress testing packet
81       transmission recovery as well as application handling of lossy
82       networks.
83
84       The coap_session_set_max_retransmit() function updates the session
85       maximum retransmit count with the new value. The default value is 4.
86
87       The coap_session_set_ack_timeout() function updates the session initial
88       ack or response timeout with the new value. The default value is 2.0.
89
90       The coap_session_set_ack_random_factor() function updates the session
91       ack random wait factor, used to randomize re-transmissions, with the
92       new value. The default value is 1.5.
93
94       The coap_session_get_max_retransmit() function returns the current
95       session maximum retransmit count.
96
97       The coap_session_get_ack_timeout() function returns the current session
98       initial ack or response timeout.
99
100       The coap_session_get_ack_random_factor() function returns the current
101       session ack random wait factor.
102
103       The coap_debug_set_packet_loss() function is uses to set the packet
104       loss levels as defined in loss_level. loss_level can be set as a
105       percentage from "0%" to "100%". Alternatively, it is possible to
106       specify which packets of a packet sequence are dropped. A definition of
107       "1,5-9,11-20,101" means that packets 1, 5 through 9, 11 through 20 and
108       101 will get dropped. A maximum of 10 different packet sets is
109       supported. The packet count is reset to 0 when
110       coap_debug_set_packet_loss() is called. To remove any packet losses,
111       set the loss_level to "0%".
112

RETURN VALUES

114       coap_session_get_max_retransmit(), coap_session_get_ack_timeout() and
115       coap_session_get_ack_random_factor() return their respective current
116       values.
117
118       coap_debug_set_packet_loss() returns 0 if loss_level does not parse
119       correctly, otherwise 1 if successful.
120

TESTING

122       The libcoap recovery/re-transmit logic will only work for confirmable
123       requests.
124
125       To see what is happening (other than by sniffing the network traffic),
126       the logging level needs to be set to LOG_DEBUG in the client by using
127       coap_set_log_level(LOG_DEBUG) and coap_dtls_set_log_level(LOG_DEBUG).
128
129       The client needs to be sending confirmable requests during the test.
130
131       The server can either be stopped, or if packet loss levels are set to
132       100% by using coap_debug_set_packet_loss("100%") when receiving the
133       client requests.
134
135       NOTE: If the server end of the connection is returning ICMP unreachable
136       packets after being turned off, you will get a debug message of the
137       form "coap_network_read: unreachable", so libcoap will stop doing the
138       retries. If this is the case, then you need to make use of (on the
139       server) coap_debug_set_packet_loss("100%") or put in some packet
140       filtering to drop the packets.
141
142       The client should then restart transmitting the requests based on the
143       ack_timeout, ack_random_factor and max_retransmit values. The client’s
144       nack_handler will get called with COAP_NACK_TOO_MANY_RETRIES when the
145       confirmable request cannot be successfully transmitted.
146

FURTHER INFORMATION

148       See "RFC7252: The Constrained Application Protocol (CoAP)" for further
149       information.
150

BUGS

152       Please report bugs on the mailing list for libcoap:
153       libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
154       https://github.com/obgm/libcoap/issues
155

AUTHORS

157       The libcoap project <libcoap-developers@lists.sourceforge.net>
158
159
160
161coap_recovery 4.3.0               01/20/2022                  COAP_RECOVERY(3)
Impressum