From 94660f4db7775c83650681068e8b23c75cb9235f Mon Sep 17 00:00:00 2001
From: Ken Bannister <kb2ma@runbox.com>
Date: Sat, 29 Dec 2018 11:49:53 -0500
Subject: [PATCH 1/3] net/coap: allow user to configure message retry macros

---
 sys/include/net/coap.h | 40 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 36 insertions(+), 4 deletions(-)

diff --git a/sys/include/net/coap.h b/sys/include/net/coap.h
index 23a4db50bd..66313cfff4 100644
--- a/sys/include/net/coap.h
+++ b/sys/include/net/coap.h
@@ -157,20 +157,52 @@ extern "C" {
 /** @} */
 
 /**
- * @name    Timing parameters
+ * @defgroup net_coap_conf    CoAP compile configurations
+ * @ingroup  net_coap
+ * @ingroup  config
  * @{
  */
-#define COAP_ACK_TIMEOUT        (2U)
-#define COAP_RANDOM_FACTOR      (1.5)
 /**
- * @brief   Maximum variation for confirmable timeout.
+ * @brief    Timeout in seconds for a response to a confirmable request
+ *
+ * This value is for the response to the *initial* confirmable message. The
+ * timeout doubles for subsequent retries. To avoid synchronization of resends
+ * across hosts, the actual timeout is chosen randomly between
+ * @ref COAP_ACK_TIMEOUT and (@ref COAP_ACK_TIMEOUT * @ref COAP_RANDOM_FACTOR).
+ */
+#ifndef COAP_ACK_TIMEOUT
+#define COAP_ACK_TIMEOUT        (2U)
+#endif
+
+/** @brief   Used to calculate upper bound for timeout; see @ref COAP_ACK_TIMEOUT */
+#ifndef COAP_RANDOM_FACTOR
+#define COAP_RANDOM_FACTOR      (1.5)
+#endif
+
+/**
+ * @brief   Approximation for maximum variation for confirmable timeout
  *
  * Must be an integer, defined as:
  *
  *     (COAP_ACK_TIMEOUT * COAP_RANDOM_FACTOR) - COAP_ACK_TIMEOUT
+ *
+ * Like @ref COAP_ACK_TIMEOUT, this value is valid for the initial confirmable
+ * message, and doubles for subsequent retries.
  */
+#ifndef COAP_ACK_VARIANCE
 #define COAP_ACK_VARIANCE       (1U)
+#endif
+
+/** @brief   Maximum number of retransmissions for a confirmable request */
+#ifndef COAP_MAX_RETRANSMIT
 #define COAP_MAX_RETRANSMIT     (4)
+#endif
+/** @} */
+
+/**
+ * @name    Timing parameters
+ * @{
+ */
 #define COAP_NSTART             (1)
 #define COAP_DEFAULT_LEISURE    (5)
 /** @} */

From 663bb5bb3d389e1ef69bd2dec4799456887eeb0d Mon Sep 17 00:00:00 2001
From: Ken Bannister <kb2ma@runbox.com>
Date: Sun, 30 Dec 2018 10:19:45 -0500
Subject: [PATCH 2/3] net/coap: use separate name for macro doc

---
 sys/include/net/coap.h | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/sys/include/net/coap.h b/sys/include/net/coap.h
index 66313cfff4..25b42b332a 100644
--- a/sys/include/net/coap.h
+++ b/sys/include/net/coap.h
@@ -162,6 +162,10 @@ extern "C" {
  * @ingroup  config
  * @{
  */
+/**
+ * @name    Timing parameters
+ * @{
+ */
 /**
  * @brief    Timeout in seconds for a response to a confirmable request
  *
@@ -198,9 +202,10 @@ extern "C" {
 #define COAP_MAX_RETRANSMIT     (4)
 #endif
 /** @} */
+/** @} */
 
 /**
- * @name    Timing parameters
+ * @name    Fixed timing parameters
  * @{
  */
 #define COAP_NSTART             (1)

From 5f8e993faf1606fb68864897ae57993e287fd226 Mon Sep 17 00:00:00 2001
From: Ken Bannister <kb2ma@runbox.com>
Date: Sun, 30 Dec 2018 10:32:08 -0500
Subject: [PATCH 3/3] net/coap: reference RFC for configurability

---
 sys/include/net/coap.h | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/sys/include/net/coap.h b/sys/include/net/coap.h
index 25b42b332a..425b4daed1 100644
--- a/sys/include/net/coap.h
+++ b/sys/include/net/coap.h
@@ -164,6 +164,9 @@ extern "C" {
  */
 /**
  * @name    Timing parameters
+ *
+ * These parameters are defined as configurable in [RFC 7252, section 4.8.1]
+ * (https://tools.ietf.org/html/rfc7252#section-4.8.1).
  * @{
  */
 /**
@@ -192,6 +195,8 @@ extern "C" {
  *
  * Like @ref COAP_ACK_TIMEOUT, this value is valid for the initial confirmable
  * message, and doubles for subsequent retries.
+ *
+ * This parameter is nanocoap-specific, and is not defined in RFC 7252.
  */
 #ifndef COAP_ACK_VARIANCE
 #define COAP_ACK_VARIANCE       (1U)