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_transmit, 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 <coap2/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_transmit(coap_session_t *session);
25
26       coap_fixed_point_t coap_session_get_ack_timeout(coap_session_t
27       *session);
28
29       coap_fixed_point_t coap_session_get_ack_random_factor(coap_session_t
30       *session);
31
32       int coap_debug_set_packet_loss(const char *loss_level);
33
34       Link with -lcoap-2, -lcoap-2-gnutls, -lcoap-2-openssl or
35       -lcoap-2-tinydtls depending on your (D)TLS library type.
36

DESCRIPTION

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

RETURN VALUES

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

TESTING

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

FURTHER INFORMATION

145       See "RFC7252: The Constrained Application Protocol (CoAP)" for further
146       information.
147

BUGS

149       Please report bugs on the mailing list for libcoap:
150       libcoap-developers@lists.sourceforge.net
151

AUTHORS

153       The libcoap project <libcoap-developers@lists.sourceforge.net>
154
155
156
157coap_recovery 4.2.1               01/26/2021                  COAP_RECOVERY(3)
Impressum