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

NAME

6       coap_recovery, coap_session_set_ack_random_factor,
7       coap_session_get_ack_random_factor, coap_session_set_ack_timeout,
8       coap_session_get_ack_timeout, coap_session_set_default_leisure,
9       coap_session_get_default_leisure, coap_session_set_max_retransmit,
10       coap_session_get_max_retransmit, coap_session_set_nstart,
11       coap_session_get_nstart, coap_session_set_probing_wait,
12       coap_session_get_probing_wait, coap_debug_set_packet_loss - Work with
13       CoAP packet transmissions
14

SYNOPSIS

16       #include <coap3/coap.h>
17
18       void coap_session_set_ack_random_factor(coap_session_t *session,
19       coap_fixed_point_t value);
20
21       coap_fixed_point_t coap_session_get_ack_random_factor( const
22       coap_session_t *session);
23
24       void coap_session_set_ack_timeout(coap_session_t *session,
25       coap_fixed_point_t value);
26
27       coap_fixed_point_t coap_session_get_ack_timeout( const coap_session_t
28       *session);
29
30       void coap_session_set_default_leisure(coap_session_t *session,
31       coap_fixed_point_t value);
32
33       coap_fixed_point_t coap_session_get_default_leisure( const
34       coap_session_t *session);
35
36       void coap_session_set_max_retransmit(coap_session_t *session, uint16_t
37       value);
38
39       uint16_t coap_session_get_max_retransmit(const coap_session_t
40       *session);
41
42       void coap_session_set_nstart(coap_session_t *session, uint16_t value);
43
44       uint16_t coap_session_get_nstart(const coap_session_t *session);
45
46       void coap_session_set_probing_rate(coap_session_t *session, uint32_t
47       value);
48
49       uint32_t coap_session_get_probing_rate(const coap_session_t *session);
50
51       int coap_debug_set_packet_loss(const char *loss_level);
52
53       For specific (D)TLS library support, link with -lcoap-3-notls,
54       -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
55       -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
56       (D)TLS library support.
57

DESCRIPTION

59       For CoAP Confirmable messages, it is possible to define the retry
60       counts, repeat rate etc. for error recovery. Further information can be
61       found in "RFC7272: 4.2. Messages Transmitted Reliably", with the
62       default values defined in "RFC7272: 4.8 Transmission Parameters".
63
64       It is not recommended that the suggested default setting are changed,
65       but there may be some special requirements that need different values
66       and the consequences of changing these values is fully understood.
67
68       Some of the parameters or return values are in fixed point format as
69       defined by the coap_fixed_point_t structure as below
70
71           typedef struct coap_fixed_point_t {
72             uint16_t integer_part;    /* Integer part of fixed point variable */
73             uint16_t fractional_part; /* Fractional part of fixed point variable
74                                          1/1000 (3 points) precision */
75           } coap_fixed_point_t;
76
77       The CoAP message retry rules are (with the default values to compute
78       the time)
79
80           1st retransmit after 1 * ack_timeout * ack_random factor (3 seconds)
81           2nd retransmit after 2 * ack_timeout * ack_random factor (6 seconds)
82           3rd retransmit after 3 * ack_timeout * ack_random factor (12 seconds)
83           4th retransmit after 4 * ack_timeout * ack_random factor (24 seconds)
84           5th retransmit after 5 * ack_timeout * ack_random factor (48 seconds)
85
86           As max_retransmit (by default) is 4, then the 5th retransmit does not get sent,
87           but at that point COAP_NACK_TOO_MANY_RETRIES gets raised in the nack_handler
88           (if defined). Note that the sum of the seconds is 93 matching RFC7252.
89
90       It should be noted that these retries are separate from the DTLS or TLS
91       encrypted session setup retry timeouts. For DTLS, the initial
92       requesting packet will get sent max_retransmit times before reporting
93       failure. For TLS the initial TCP connection will timeout before
94       reporting failure.
95
96       It is also possible to set up packet losses, for both confirmable, and
97       non-confirmable messages. This can be used for stress testing packet
98       transmission recovery as well as application handling of lossy
99       networks.
100
101       The following functions reflect the RFC7252 uppercase names in
102       lowercase following the coap_session[sg]_ function prefix.
103
104       The coap_session_set_ack_random_factor() function updates the session
105       ack random wait factor, used to randomize re-transmissions, with the
106       new value. The default value is 1.5.
107
108       The coap_session_get_ack_random_factor() function returns the current
109       session ack random wait factor.
110
111       The coap_session_set_ack_timeout() function updates the session initial
112       ack or response timeout with the new value. The default value is 2.0.
113
114       The coap_session_get_ack_timeout() function returns the current session
115       initial ack or response timeout.
116
117       The coap_session_set_default_leisure() function updates the session
118       default leisure time with the new value. The initial default value is
119       5.0.
120
121       The coap_session_get_default_leisure() function returns the current
122       session default leisure time.
123
124       The coap_session_set_max_retransmit() function updates the session
125       maximum retransmit count with the new value. The default value is 4.
126
127       The coap_session_get_max_retransmit() function returns the current
128       session maximum retransmit count.
129
130       The coap_session_set_nstart() function updates the session nstart with
131       the new value. The default value is 1.
132
133       The coap_session_get_nstart() function returns the current session
134       nstart value.
135
136       The coap_session_set_probing_rate() function updates the session
137       probing rate with the new value. The default value is 1 byte per
138       second.
139
140       The coap_session_get_probing_rate() function returns the current
141       session probing rate value.
142
143       The coap_debug_set_packet_loss() function is uses to set the packet
144       loss levels as defined in loss_level. loss_level can be set as a
145       percentage from "0%" to "100%". Alternatively, it is possible to
146       specify which packets of a packet sequence are dropped. A definition of
147       "1,5-9,11-20,101" means that packets 1, 5 through 9, 11 through 20 and
148       101 will get dropped. A maximum of 10 different packet sets is
149       supported. The packet count is reset to 0 when
150       coap_debug_set_packet_loss() is called. To remove any packet losses,
151       set the loss_level to "0%".
152

RETURN VALUES

154       coap_session_get_ack_random_factor(), coap_session_get_ack_timeout(),
155       coap_session_get_default_leisure(), coap_session_get_max_retransmit(),
156       coap_session_get_nstart() and coap_session_get_probing_rate() return
157       their respective current values.
158
159       coap_debug_set_packet_loss() returns 0 if loss_level does not parse
160       correctly, otherwise 1 if successful.
161

TESTING

163       The libcoap recovery/re-transmit logic will only work for confirmable
164       requests.
165
166       To see what is happening (other than by sniffing the network traffic),
167       the logging level needs to be set to LOG_DEBUG in the client by using
168       coap_set_log_level(LOG_DEBUG) and coap_dtls_set_log_level(LOG_DEBUG).
169
170       The client needs to be sending confirmable requests during the test.
171
172       The server can either be stopped, or if packet loss levels are set to
173       100% by using coap_debug_set_packet_loss("100%") when receiving the
174       client requests.
175
176       NOTE: If the server end of the connection is returning ICMP unreachable
177       packets after being turned off, you will get a debug message of the
178       form "coap_network_read: unreachable", so libcoap will stop doing the
179       retries. If this is the case, then you need to make use of (on the
180       server) coap_debug_set_packet_loss("100%") or put in some packet
181       filtering to drop the packets.
182
183       The client should then restart transmitting the requests based on the
184       ack_timeout, ack_random_factor and max_retransmit values. The client’s
185       nack_handler will get called with COAP_NACK_TOO_MANY_RETRIES when the
186       confirmable request cannot be successfully transmitted.
187

FURTHER INFORMATION

189       See "RFC7252: The Constrained Application Protocol (CoAP)" for further
190       information.
191

BUGS

193       Please report bugs on the mailing list for libcoap:
194       libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
195       https://github.com/obgm/libcoap/issues
196

AUTHORS

198       The libcoap project <libcoap-developers@lists.sourceforge.net>
199
200
201
202coap_recovery 4.3.1               01/19/2023                  COAP_RECOVERY(3)
Impressum