1COAP_RECOVERY(3) libcoap Manual COAP_RECOVERY(3)
2
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
13 #include <coap3/coap.h>
14 void coap_session_set_max_retransmit(coap_session_t *session, unsigned
16 int value);
17 void coap_session_set_ack_timeout(coap_session_t *session,
19 coap_fixed_point_t value);
20 void coap_session_set_ack_random_factor(coap_session_t *session,
22 coap_fixed_point_t value);
23 unsigned int coap_session_get_max_retransmit(const coap_session_t
25 *session);
26 coap_fixed_point_t coap_session_get_ack_timeout( const coap_session_t
28 *session);
29 coap_fixed_point_t coap_session_get_ack_random_factor( const
31 coap_session_t *session);
32 int coap_debug_set_packet_loss(const char *loss_level);
34 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
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 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 Changing the default values for multicast packets is not supported.
50 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 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 The CoAP message retry rules are (with the default values to compute
61 the time)
62 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 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 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 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 The coap_session_set_max_retransmit() function updates the session
85 maximum retransmit count with the new value. The default value is 4.
86 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 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 The coap_session_get_max_retransmit() function returns the current
95 session maximum retransmit count.
96 The coap_session_get_ack_timeout() function returns the current session
98 initial ack or response timeout.
99 The coap_session_get_ack_random_factor() function returns the current
101 session ack random wait factor.
102 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
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 coap_debug_set_packet_loss() returns 0 if loss_level does not parse
119 correctly, otherwise 1 if successful.
120
122 The libcoap recovery/re-transmit logic will only work for confirmable
123 requests.
124 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 The client needs to be sending confirmable requests during the test.
130 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 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 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
148 See "RFC7252: The Constrained Application Protocol (CoAP)" for further
149 information.
150
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
157 The libcoap project <libcoap-developers@lists.sourceforge.net>
158coap_recovery 4.3.0 07/22/2021 COAP_RECOVERY(3)