From da052ec23d03d202844aa7e5e3400324e8b8480f Mon Sep 17 00:00:00 2001 From: Lee George Thomas Date: Thu, 10 Dec 2020 16:30:46 -0800 Subject: [PATCH 1/6] Update timeout doc --- docs/doxygen/timeouts.dox | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/doxygen/timeouts.dox b/docs/doxygen/timeouts.dox index 5e04ec076..4b102d1b5 100644 --- a/docs/doxygen/timeouts.dox +++ b/docs/doxygen/timeouts.dox @@ -11,6 +11,7 @@ The timeouts and the recommended configurations are listed below. 4. [MQTT Receive Polling timeout](@ref mqtt_timeouts_receive_polling) 5. [MQTT Send Retry timeout](@ref mqtt_timeouts_send_retry) 6. [Timeouts for MQTT_ProcessLoop and MQTT_ReceiveLoop APIs](@ref mqtt_timeouts_process_receive_loop) +7. [Timeout for MQTT_Connect](@ref mqtt_timeouts_connect) @section mqtt_timeouts_transport_send_receive Transport Send and Receive timeouts These are the network send and read operation blocking timeouts used by the implementation @@ -39,10 +40,16 @@ This is to make sure that a Control packet including an MQTT ping request packet the Transport functions block for the maximum time. MQTT Keep Alive interval can be configured by setting the `keepAliveIntervalSec` member of the [MQTTContext_t](@ref mqtt_struct_types) structure. +@see @ref mqtt_keepalive + @section mqtt_timeouts_ping_response MQTT Ping Response timeout MQTT Ping Response timeout is the time to wait for a ping response to an MQTT ping request as part of the keep-alive mechanism in the MQTT Client. This timeout can be configured independent of the Transport timeouts unlike the MQTT Keep Alive -interval, since a check for this timeout is done by coreMQTT library only after an attempt to receive from Transport layer. +interval, since this timeout only depends on the MQTT broker, the platform and, the network latencies. + +We recommend to use a ping response timeout greater than the P99 ping response latency for the broker and the platform being used. +The P99 value for the ping response latency can be calculated using an MQTT application by experimenting on a sample of devices and +obtaining the data for latency of each ping response from the broker after a ping request is sent. MQTT Ping Response timeout can be set by defining the configuration @ref MQTT_PINGRESP_TIMEOUT_MS. @@ -91,4 +98,17 @@ That means, especially in multi-threaded application, the process loop timeout c faster than the MQTT Keep Alive interval. If a dummy @ref MQTTGetCurrentTimeFunc_t was passed to @ref mqtt_init_function, then the timeout must be set to 0. +@see @ref mqtt_receivetimeout + +@section mqtt_timeouts_connect Timeout for MQTT_Connect +This timeout is passed as an argument to @ref mqtt_connect_function. It is the maximum time to wait for an MQTT CONNACK packet. If this value is +set to 0, then instead of a time-based loop, it will attempt to call the Transport Receive function up to a fixed maximum number of times, +which is defined by @ref MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT. + +We recommend to use a timeout value greater than the P99 latency for receiving the MQTT CONNACK packet from the broker on the platform being used. +The P99 value for this latency can be calculated using an MQTT application by experimenting on a sample of devices and obtaining the data for +latency to receive each MQTT CONNACK packet from the broker after an MQTT CONNECT packet is sent. + +@see @ref mqtt_receivetimeout + */ From 4b858f220a6474b0556e3d7ef76ad84952ecf415 Mon Sep 17 00:00:00 2001 From: Lee George Thomas Date: Thu, 10 Dec 2020 16:47:00 -0800 Subject: [PATCH 2/6] Update timeout doc 1 --- docs/doxygen/timeouts.dox | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/doxygen/timeouts.dox b/docs/doxygen/timeouts.dox index 4b102d1b5..d67ad0de9 100644 --- a/docs/doxygen/timeouts.dox +++ b/docs/doxygen/timeouts.dox @@ -47,9 +47,9 @@ MQTT Ping Response timeout is the time to wait for a ping response to an MQTT pi mechanism in the MQTT Client. This timeout can be configured independent of the Transport timeouts unlike the MQTT Keep Alive interval, since this timeout only depends on the MQTT broker, the platform and, the network latencies. -We recommend to use a ping response timeout greater than the P99 ping response latency for the broker and the platform being used. -The P99 value for the ping response latency can be calculated using an MQTT application by experimenting on a sample of devices and -obtaining the data for latency of each ping response from the broker after a ping request is sent. +We recommend to choose a ping response timeout by experimenting with an MQTT application on a sample of devices and obtaining the data +for latency of each ping response from the broker after a ping request is sent. A timeout value can then be chosen based on the statistical +measure suitable for the end application, such as 99th percentile or average. MQTT Ping Response timeout can be set by defining the configuration @ref MQTT_PINGRESP_TIMEOUT_MS. @@ -105,9 +105,9 @@ This timeout is passed as an argument to @ref mqtt_connect_function. It is the m set to 0, then instead of a time-based loop, it will attempt to call the Transport Receive function up to a fixed maximum number of times, which is defined by @ref MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT. -We recommend to use a timeout value greater than the P99 latency for receiving the MQTT CONNACK packet from the broker on the platform being used. -The P99 value for this latency can be calculated using an MQTT application by experimenting on a sample of devices and obtaining the data for -latency to receive each MQTT CONNACK packet from the broker after an MQTT CONNECT packet is sent. +We recommend to choose a timeout for @ref mqtt_connect_function by experimenting with an MQTT application on a sample of devices and +obtaining the data for latency of each CONNACK packet from the broker after an MQTT CONNECT packet is sent. A timeout value can then be chosen +based on the statistical measure suitable for the end application, such as 99th percentile or average. @see @ref mqtt_receivetimeout From 488abc8f98fab02501f9377cc98c5e195d00b3dc Mon Sep 17 00:00:00 2001 From: leegeth <51681119+leegeth@users.noreply.github.com> Date: Thu, 10 Dec 2020 16:49:06 -0800 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Archit Aggarwal --- docs/doxygen/timeouts.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/doxygen/timeouts.dox b/docs/doxygen/timeouts.dox index d67ad0de9..e9daa1842 100644 --- a/docs/doxygen/timeouts.dox +++ b/docs/doxygen/timeouts.dox @@ -45,7 +45,7 @@ the Transport functions block for the maximum time. MQTT Keep Alive interval can @section mqtt_timeouts_ping_response MQTT Ping Response timeout MQTT Ping Response timeout is the time to wait for a ping response to an MQTT ping request as part of the keep-alive mechanism in the MQTT Client. This timeout can be configured independent of the Transport timeouts unlike the MQTT Keep Alive -interval, since this timeout only depends on the MQTT broker, the platform and, the network latencies. +interval, since this timeout only depends on the MQTT broker, the platform and the network latencies. We recommend to choose a ping response timeout by experimenting with an MQTT application on a sample of devices and obtaining the data for latency of each ping response from the broker after a ping request is sent. A timeout value can then be chosen based on the statistical From 2067fd8e2d37688be7e6da4702a410bba0d216e3 Mon Sep 17 00:00:00 2001 From: leegeth <51681119+leegeth@users.noreply.github.com> Date: Thu, 10 Dec 2020 17:03:53 -0800 Subject: [PATCH 4/6] Update docs/doxygen/timeouts.dox --- docs/doxygen/timeouts.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/doxygen/timeouts.dox b/docs/doxygen/timeouts.dox index e9daa1842..0ed51d169 100644 --- a/docs/doxygen/timeouts.dox +++ b/docs/doxygen/timeouts.dox @@ -102,7 +102,7 @@ then the timeout must be set to 0. @section mqtt_timeouts_connect Timeout for MQTT_Connect This timeout is passed as an argument to @ref mqtt_connect_function. It is the maximum time to wait for an MQTT CONNACK packet. If this value is -set to 0, then instead of a time-based loop, it will attempt to call the Transport Receive function up to a fixed maximum number of times, +set to 0, then instead of a time-based loop, it will attempt to call the Transport Receive function up to a maximum number of retries, which is defined by @ref MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT. We recommend to choose a timeout for @ref mqtt_connect_function by experimenting with an MQTT application on a sample of devices and From 2921b6afd3920d0cb96ef8ecbb3e5ef47f9f1aef Mon Sep 17 00:00:00 2001 From: leegeth <51681119+leegeth@users.noreply.github.com> Date: Thu, 10 Dec 2020 17:04:59 -0800 Subject: [PATCH 5/6] Update docs/doxygen/timeouts.dox Co-authored-by: Archit Aggarwal --- docs/doxygen/timeouts.dox | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/doxygen/timeouts.dox b/docs/doxygen/timeouts.dox index 0ed51d169..574f22e8b 100644 --- a/docs/doxygen/timeouts.dox +++ b/docs/doxygen/timeouts.dox @@ -95,8 +95,7 @@ being half way through a packet and will just error and disconnect if you don't That means, especially in multi-threaded application, the process loop timeout can be zero. @ref mqtt_processloop_function API can be used to manage the MQTT keep-alive mechanism and if used, application must invoke this API -faster than the MQTT Keep Alive interval. If a dummy @ref MQTTGetCurrentTimeFunc_t was passed to @ref mqtt_init_function, -then the timeout must be set to 0. +faster than the MQTT Keep Alive interval. If a dummy @ref MQTTGetCurrentTimeFunc_t was passed to @ref mqtt_init_function, then the keep-alive mechanism is not supported by the @ref mqtt_processloop_function API; instead the @ref mqtt_receiveloop_function should be used. @see @ref mqtt_receivetimeout From a9b552b8bfa00135e989c7e3442207eb575aa9f3 Mon Sep 17 00:00:00 2001 From: leegeth <51681119+leegeth@users.noreply.github.com> Date: Thu, 10 Dec 2020 17:16:31 -0800 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Archit Aggarwal --- docs/doxygen/timeouts.dox | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/doxygen/timeouts.dox b/docs/doxygen/timeouts.dox index 574f22e8b..227f1179b 100644 --- a/docs/doxygen/timeouts.dox +++ b/docs/doxygen/timeouts.dox @@ -47,8 +47,8 @@ MQTT Ping Response timeout is the time to wait for a ping response to an MQTT pi mechanism in the MQTT Client. This timeout can be configured independent of the Transport timeouts unlike the MQTT Keep Alive interval, since this timeout only depends on the MQTT broker, the platform and the network latencies. -We recommend to choose a ping response timeout by experimenting with an MQTT application on a sample of devices and obtaining the data -for latency of each ping response from the broker after a ping request is sent. A timeout value can then be chosen based on the statistical +We recommend to choose a ping response timeout by experimenting with an MQTT application on a sample of devices and collecting the data +of latency for each ping response from the broker after a ping request is sent. A timeout value can then be chosen based on the statistical measure suitable for the end application, such as 99th percentile or average. MQTT Ping Response timeout can be set by defining the configuration @ref MQTT_PINGRESP_TIMEOUT_MS. @@ -105,7 +105,7 @@ set to 0, then instead of a time-based loop, it will attempt to call the Transpo which is defined by @ref MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT. We recommend to choose a timeout for @ref mqtt_connect_function by experimenting with an MQTT application on a sample of devices and -obtaining the data for latency of each CONNACK packet from the broker after an MQTT CONNECT packet is sent. A timeout value can then be chosen +collecting the data of latency for each CONNACK packet received from the broker after an MQTT CONNECT packet is sent. A timeout value can then be chosen based on the statistical measure suitable for the end application, such as 99th percentile or average. @see @ref mqtt_receivetimeout