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_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
16 #include <coap3/coap.h>
17 void coap_session_set_ack_random_factor(coap_session_t *session,
19 coap_fixed_point_t value);
20 coap_fixed_point_t coap_session_get_ack_random_factor( const
22 coap_session_t *session);
23 void coap_session_set_ack_timeout(coap_session_t *session,
25 coap_fixed_point_t value);
26 coap_fixed_point_t coap_session_get_ack_timeout( const coap_session_t
28 *session);
29 void coap_session_set_default_leisure(coap_session_t *session,
31 coap_fixed_point_t value);
32 coap_fixed_point_t coap_session_get_default_leisure( const
34 coap_session_t *session);
35 void coap_session_set_max_retransmit(coap_session_t *session, uint16_t
37 value);
38 uint16_t coap_session_get_max_retransmit(const coap_session_t
40 *session);
41 void coap_session_set_nstart(coap_session_t *session, uint16_t value);
43 uint16_t coap_session_get_nstart(const coap_session_t *session);
45 void coap_session_set_probing_rate(coap_session_t *session, uint32_t
47 value);
48 uint32_t coap_session_get_probing_rate(const coap_session_t *session);
50 int coap_debug_set_packet_loss(const char *loss_level);
52 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
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 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 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 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 The CoAP message retry rules are (with the default values to compute
78 the time)
79 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 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 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 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 The following functions reflect the RFC7252 uppercase names in
102 lowercase following the coap_session[sg]_ function prefix.
103 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 The coap_session_get_ack_random_factor() function returns the current
109 session ack random wait factor.
110 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 The coap_session_get_ack_timeout() function returns the current session
115 initial ack or response timeout.
116 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 The coap_session_get_default_leisure() function returns the current
122 session default leisure time.
123 The coap_session_set_max_retransmit() function updates the session
125 maximum retransmit count with the new value. The default value is 4.
126 The coap_session_get_max_retransmit() function returns the current
128 session maximum retransmit count.
129 The coap_session_set_nstart() function updates the session nstart with
131 the new value. The default value is 1.
132 The coap_session_get_nstart() function returns the current session
134 nstart value.
135 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 The coap_session_get_probing_rate() function returns the current
141 session probing rate value.
142 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
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 coap_debug_set_packet_loss() returns 0 if loss_level does not parse
160 correctly, otherwise 1 if successful.
161
163 The libcoap recovery/re-transmit logic will only work for confirmable
164 requests.
165 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 The client needs to be sending confirmable requests during the test.
171 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 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 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
189 See "RFC7252: The Constrained Application Protocol (CoAP)" for further
190 information.
191
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
198 The libcoap project <libcoap-developers@lists.sourceforge.net>
199coap_recovery 4.3.1 01/19/2023 COAP_RECOVERY(3)