1COAP_RECOVERY(3) libcoap Manual COAP_RECOVERY(3)
2
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_payloads,
10 coap_session_get_max_payloads, coap_session_set_max_retransmit,
11 coap_session_get_max_retransmit, coap_session_set_non_max_retransmit,
12 coap_session_get_non_max_retransmit,
13 coap_session_set_non_receive_timeout,
14 coap_session_get_non_receive_timeout, coap_session_set_non_timeout,
15 coap_session_get_non_timeout, coap_session_set_nstart,
16 coap_session_get_nstart, coap_session_set_probing_rate,
17 coap_session_get_probing_rate, coap_debug_set_packet_loss - Work with
18 CoAP packet transmissions
19
21 #include <coap3/coap.h>
22 void coap_session_set_ack_random_factor(coap_session_t *session,
24 coap_fixed_point_t value);
25 coap_fixed_point_t coap_session_get_ack_random_factor( const
27 coap_session_t *session);
28 void coap_session_set_ack_timeout(coap_session_t *session,
30 coap_fixed_point_t value);
31 coap_fixed_point_t coap_session_get_ack_timeout( const coap_session_t
33 *session);
34 void coap_session_set_default_leisure(coap_session_t *session,
36 coap_fixed_point_t value);
37 coap_fixed_point_t coap_session_get_default_leisure( const
39 coap_session_t *session);
40 void coap_session_set_max_payloads(coap_session_t *session, uint16_t
42 value);
43 uint16_t coap_session_get_max_payloads(const coap_session_t *session);
45 void coap_session_set_max_retransmit(coap_session_t *session, uint16_t
47 value);
48 uint16_t coap_session_get_max_retransmit(const coap_session_t
50 *session);
51 void coap_session_set_non_max_retransmit(coap_session_t *session,
53 uint16_t value);
54 uint16_t coap_session_get_non_max_retransmit(const coap_session_t
56 *session);
57 void coap_session_set_non_receive_timeout(coap_session_t *session,
59 coap_fixed_point_t value);
60 coap_fixed_point_t coap_session_get_non_receive_timeout( const
62 coap_session_t *session);
63 void coap_session_set_non_timeout(coap_session_t *session,
65 coap_fixed_point_t value);
66 coap_fixed_point_t coap_session_get_non_timeout( const coap_session_t
68 *session);
69 void coap_session_set_nstart(coap_session_t *session, uint16_t value);
71 uint16_t coap_session_get_nstart(const coap_session_t *session);
73 void coap_session_set_probing_rate(coap_session_t *session, uint32_t
75 value);
76 uint32_t coap_session_get_probing_rate(const coap_session_t *session);
78 int coap_debug_set_packet_loss(const char *loss_level);
80 For specific (D)TLS library support, link with -lcoap-3-notls,
82 -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
83 -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
84 (D)TLS library support.
85
87 There is CoAP Confirmable message transmission recovery as defined in
88 RFC7252, as well CoAP Non-Confirmable split into blocks message
89 transmission recovery support as defined in RFC9177.
90 For CoAP Confirmable messages, it is possible to define the retry
92 counts, repeat rate etc. for error recovery. Further information can be
93 found in "RFC7272 4.2. Messages Transmitted Reliably", with the default
94 values defined in "RFC7272 4.8. Transmission Parameters".
95 It is not recommended that the suggested default setting are changed,
97 but there may be some special requirements that need different values
98 and the consequences of changing these values is fully understood.
99 Some of the parameters or return values are in fixed point format as
101 defined by the coap_fixed_point_t structure as below
102 typedef struct coap_fixed_point_t {
104 uint16_t integer_part; /* Integer part of fixed point variable */
105 uint16_t fractional_part; /* Fractional part of fixed point variable
106 1/1000 (3 points) precision */
107 } coap_fixed_point_t;
108 The CoAP Confirmable message retry rules are (with the default values
110 to compute the time)
111 1st retransmit after 1 * ack_timeout * ack_random factor (3 seconds)
113 2nd retransmit after 2 * ack_timeout * ack_random factor (6 seconds)
114 3rd retransmit after 3 * ack_timeout * ack_random factor (12 seconds)
115 4th retransmit after 4 * ack_timeout * ack_random factor (24 seconds)
116 5th retransmit after 5 * ack_timeout * ack_random factor (48 seconds)
117 As max_retransmit (by default) is 4, then the 5th retransmit does not get sent,
119 but at that point COAP_NACK_TOO_MANY_RETRIES gets raised in the nack_handler
120 (if defined). Note that the sum of the seconds is 93 matching
121 "https://rfc-editor.org/rfc/rfc7252#section-4.8.2[RFC7252 4.8.2.
122 MAX_TRANSMIT_WAIT]".
123 It should be noted that these retries are separate from the DTLS or TLS
125 encrypted session setup retry timeouts. For DTLS, the initial
126 requesting packet will get sent max_retransmit times before reporting
127 failure. For TLS the initial TCP connection will timeout before
128 reporting failure.
129 For CoAP Non-Confirmable messages with RFC9177 enabled at both ends of
131 a session, it is possible to define the retry counts etc. for data
132 recovery. Further information can be found in "RFC9177 7.2.
133 Non-confirmable (NON)".
134 It is also possible to set up packet losses, for both confirmable, and
136 non-confirmable messages. This can be used for stress testing packet
137 transmission recovery as well as application handling of lossy
138 networks.
139
141 The following functions reflect the RFC7252 and RFC9177 uppercase names
142 in lowercase following the coap_session_set_ or coap_session_get_
143 function prefix.
144 Function: coap_session_set_ack_random_factor()
146 The coap_session_set_ack_random_factor() function updates the session
148 ack random wait factor, used to randomize re-transmissions, with the
149 new value. The default value is 1.5 (RFC7252).
150 Function: coap_session_get_ack_random_factor()
152 The coap_session_get_ack_random_factor() function returns the current
154 session ack random wait factor (RFC7252).
155 Function: coap_session_set_ack_timeout()
157 The coap_session_set_ack_timeout() function updates the session initial
159 ack or response timeout with the new value. The default value is 2.0
160 (RFC7252).
161 Function: coap_session_get_ack_timeout()
163 The coap_session_get_ack_timeout() function returns the current session
165 initial ack or response timeout (RFC7252).
166 Function: coap_session_set_default_leisure()
168 The coap_session_set_default_leisure() function updates the session
170 default leisure time with the new value. The default value is 5.0
171 (RFC7252).
172 Function: coap_session_get_default_leisure()
174 The coap_session_get_default_leisure() function returns the current
176 session default leisure time (RFC7252).
177 Function: coap_session_set_max_payloads()
179 The coap_session_set_max_payloads() function updates the session
181 maximum payloads count with the new value. The default value is 10
182 (RFC9177).
183 NOTE: Both ends of the session must have the same maximum payloads
185 value to minimize any recovery times.
186 Function: coap_session_get_max_payloads()
188 The coap_session_get_max_payloads() function returns the current
190 session maximum payloads count (RFC9177).
191 Function: coap_session_set_max_retransmit()
193 The coap_session_set_max_retransmit() function updates the session
195 maximum retransmit count with the new value. The default value is 4
196 (RFC7252).
197 Function: coap_session_get_max_retransmit()
199 The coap_session_get_max_retransmit() function returns the current
201 session maximum retransmit count (RFC7252).
202 Function: coap_session_set_non_max_retransmit()
204 The coap_session_set_non_max_retransmit() function updates the session
206 maximum non retransmit count with the new value. The default value is 4
207 (RFC9177).
208 Function: coap_session_get_non_max_retransmit()
210 The coap_session_get_non_max_retransmit() function returns the current
212 session maximum non retransmit count (RFC9177).
213 Function: coap_session_set_non_receive_timeout()
215 The coap_session_set_non_receive_timeout() function updates the session
217 non receive timeout with the new value. The default value is 4.0
218 (RFC9177).
219 Function: coap_session_get_non_receive_timeout()
221 The coap_session_get_non_receive_timeout() function returns the current
223 session non receive timeout (RFC9177).
224 Function: coap_session_set_non_timeout()
226 The coap_session_set_non_timeout() function updates the session non
228 timeout with the new value. The default value is 2.0 (RFC9177).
229 Function: coap_session_get_non_timeout()
231 The coap_session_get_non_timeout() function returns the current session
233 non timeout (RFC9177).
234 Function: coap_session_set_nstart()
236 The coap_session_set_nstart() function updates the session nstart with
238 the new value. The default value is 1 (RFC7252).
239 Function: coap_session_set_probing_rate()
241 The coap_session_get_nstart() function returns the current session
243 nstart value (RFC7252).
244 Function: coap_session_set_probing_rate()
246 The coap_session_set_probing_rate() function updates the session
248 probing rate with the new value. The default value is 1 byte per second
249 (RFC7252).
250 Function: coap_session_get_probing_rate()
252 The coap_session_get_probing_rate() function returns the current
254 session probing rate value (RFC7252).
255 Function: coap_debug_set_packet_loss()
257 The coap_debug_set_packet_loss() function is uses to set the packet
259 loss levels as defined in loss_level. loss_level can be set as a
260 percentage from "0%" to "100%". Alternatively, it is possible to
261 specify which packets of a packet sequence are dropped. A definition of
262 "1,5-9,11-20,101" means that packets 1, 5 through 9, 11 through 20 and
263 101 will get dropped. A maximum of 10 different packet sets is
264 supported. The packet count is reset to 0 when
265 coap_debug_set_packet_loss() is called. To remove any packet losses,
266 set the loss_level to "0%".
267
269 coap_session_get_ack_random_factor(), coap_session_get_ack_timeout(),
270 coap_session_get_default_leisure(), coap_session_get_max_payloads(),
271 coap_session_get_max_retransmit(),
272 coap_session_get_non_max_retransmit(),
273 coap_session_get_non_receive_timeout(), coap_session_get_non_timeout(),
274 coap_session_get_nstart() and coap_session_get_probing_rate() return
275 their respective current values.
276 coap_debug_set_packet_loss() returns 0 if loss_level does not parse
278 correctly, otherwise 1 if successful.
279
281 The libcoap RFC7252 recovery/re-transmit logic will only work for
282 confirmable requests or if RFC9177 support is enabled for
283 non-confirmable large body transmissions that need to span multiple
284 packets.
285 To see what is happening (other than by sniffing the network traffic),
287 the logging level needs to be set to COAP_LOG_DEBUG in the client by
288 using coap_set_log_level(COAP_LOG_DEBUG) and
289 coap_dtls_set_log_level(COAP_LOG_DEBUG).
290 The server can either be stopped, or if packet loss levels are set to
292 100% by using coap_debug_set_packet_loss("100%") when receiving the
293 client requests.
294 NOTE: If the server end of the connection is returning ICMP unreachable
296 packets after being turned off, you will get a debug message of the
297 form "coap_network_read: unreachable", so libcoap will stop doing the
298 retries. If this is the case, then you need to make use of (on the
299 server) coap_debug_set_packet_loss("100%") or put in some packet
300 filtering to drop the packets.
301 For confirmable transmissions, the client should then restart
303 transmitting the requests based on the ack_timeout, ack_random_factor
304 and max_retransmit values. The client’s nack_handler will get called
305 with COAP_NACK_TOO_MANY_RETRIES when the confirmable request cannot be
306 successfully transmitted.
307 For non-confirmable block transmissions (RFC9177 enabled), the client
309 should then restart transmitting the missing requests based on the
310 max_payloads, non_timeout, non_receive_timeout, and non_max_retransmit
311 values. The client’s nack_handler will get called with
312 COAP_NACK_TOO_MANY_RETRIES when the non-confirmable large body request
313 cannot be successfully transmitted.
314
316 See
317 "RFC7252: The Constrained Application Protocol (CoAP)"
319 "RFC9177: Constrained Application Protocol (CoAP) Block-Wise Transfer
321 Options Supporting Robust Transmission"
322 for further information.
324
326 Please report bugs on the mailing list for libcoap:
327 libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
328 https://github.com/obgm/libcoap/issues
329
331 The libcoap project <libcoap-developers@lists.sourceforge.net>
332coap_recovery 4.3.4 10/09/2023 COAP_RECOVERY(3)