Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update timeout doc #138

Merged
merged 6 commits into from
Dec 11, 2020
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 22 additions & 3 deletions docs/doxygen/timeouts.dox
Original file line number Diff line number Diff line change
@@ -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 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.

@@ -88,7 +95,19 @@ 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

@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 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
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
leegeth marked this conversation as resolved.
Show resolved Hide resolved

*/