diff --git a/docs/doxygen/pages.dox b/docs/doxygen/pages.dox index 0a4f5b24b..36b501a0a 100644 --- a/docs/doxygen/pages.dox +++ b/docs/doxygen/pages.dox @@ -61,11 +61,11 @@ This MQTT client library provides an implementation of the [MQTT 3.1.1 specifica @section mqtt_interfaces Interfaces and Callbacks -The MQTT library relies on interfaces to dissociate itself from platform specific areas, -such as the transport layer or maintaining time. Interfaces used by MQTT are simply function callbacks +The MQTT library relies on interfaces to dissociate itself from platform specific functionality, +such as the transport layer or maintaining time. Interfaces used by MQTT are simply function pointers with expectations of behavior. -The MQTT library expects the following interfaces: +The MQTT library expects the application to provide implementations for the following interfaces: @@ -141,15 +141,16 @@ wait for acknowledgments, a call to @ref mqtt_processloop_function or @ref mqtt_ The exception is @ref mqtt_connect_function; since a MQTT session cannot be considered established until the server acknowledges a CONNECT packet with a CONNACK, the function waits until the CONNACK is received. -@subsection mqtt_receivetimeout Timeouts +@subsection mqtt_receivetimeout Runtime Timeouts passed to MQTT library @ref mqtt_connect_function, @ref mqtt_processloop_function, and @ref mqtt_receiveloop_function all accept a timeout parameter for packet reception.
-For the @ref mqtt_connect_function, 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. +For the @ref mqtt_connect_function, 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. For @ref mqtt_processloop_function and @ref mqtt_receiveloop_function, the timeout value represents the minimum duration that will be spent in the function, provided there are no network errors. -Should the timeout be set to 0, then the loop will run for a single iteration. A single iteration of a loop consists of an attempt to receive a single byte from the network, -followed by the reception of the entire packet if the receive was successful, and finally deserialization of the packet received and a call to the application callback. If the first read did not succeed, -then instead the library checks if a ping request needs to be sent (only for the process loop). +Should the timeout be set to 0, then the loop will run for a single iteration. A single iteration of a loop consists of an attempt to receive a single byte from the network, and +if the single byte receive was successful, then attempt(s) to receive the rest of the packet (with retry attempts governed by @ref MQTT_RECV_POLLING_TIMEOUT_MS), followed by sending acknowledgement response, if needed +(with retry attempts governed by @ref MQTT_SEND_RETRY_TIMEOUT_MS), and then, finally deserialization of the packet received and a call to the application callback. +If the first read did not succeed, then instead the library checks if a ping request needs to be sent (only for the process loop). See the below diagrams for a representation of the above flows: | MQTT Connect Diagram | MQTT ProcessLoop Diagram | MQTT ReceiveLoop Diagram | diff --git a/docs/plantuml/images/mqtt_connect_design.png b/docs/plantuml/images/mqtt_connect_design.png index 28e9dfd1a..81a1933c6 100644 Binary files a/docs/plantuml/images/mqtt_connect_design.png and b/docs/plantuml/images/mqtt_connect_design.png differ diff --git a/docs/plantuml/images/mqtt_processloop_design.png b/docs/plantuml/images/mqtt_processloop_design.png index 7055bf3ac..cffe3d256 100644 Binary files a/docs/plantuml/images/mqtt_processloop_design.png and b/docs/plantuml/images/mqtt_processloop_design.png differ diff --git a/docs/plantuml/images/mqtt_receiveloop_design.png b/docs/plantuml/images/mqtt_receiveloop_design.png index 117694efc..d86b72b52 100644 Binary files a/docs/plantuml/images/mqtt_receiveloop_design.png and b/docs/plantuml/images/mqtt_receiveloop_design.png differ diff --git a/docs/plantuml/mqtt_connect_design.pu b/docs/plantuml/mqtt_connect_design.pu index bcab2f013..e89eb4a6b 100644 --- a/docs/plantuml/mqtt_connect_design.pu +++ b/docs/plantuml/mqtt_connect_design.pu @@ -8,10 +8,13 @@ start repeat : Receive single byte; -repeat while (No network data AND \ncount < MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT) is (yes) +repeat while ( No network data available AND \n retry count < MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT) is (yes) -> no or timeout == 0; -: Get rest of CONNACK packet; +repeat + : Get rest of CONNACK packet; + note left: Retry zero byte reads for maximum period \nof **MQTT_RECV_POLLING_TIMEOUT_MS** +repeat while( Received complete packet? ) is ( no ) : Deserialize CONNACK packet; stop diff --git a/docs/plantuml/mqtt_processloop_design.pu b/docs/plantuml/mqtt_processloop_design.pu index 8218cb92b..2549b27f4 100644 --- a/docs/plantuml/mqtt_processloop_design.pu +++ b/docs/plantuml/mqtt_processloop_design.pu @@ -6,10 +6,20 @@ start repeat : Receive single byte; - if( success ) then (yes) - : Get rest of packet; + if( read successful? ) then (yes) + repeat + : Get rest of packet; + note left: Retry zero byte reads for maximum period \nof **MQTT_RECV_POLLING_TIMEOUT_MS** + repeat while( Received complete packet? ) is ( no ) : Deserialize packet; - : Application callback; + if ( Need to send ACK response? ) then (yes) + repeat + : Send ACK packet; + note left: Retry zero byte sends for maximum period \nof **MQTT_SEND_RETRY_TIMEOUT_MS** + repeat while( Sent complete packet? ) is ( no ) + else (no) + endif + : Invoke Application callback; else (no) : Manage Keep-Alive; endif diff --git a/docs/plantuml/mqtt_receiveloop_design.pu b/docs/plantuml/mqtt_receiveloop_design.pu index 650a12ba1..845eaa874 100644 --- a/docs/plantuml/mqtt_receiveloop_design.pu +++ b/docs/plantuml/mqtt_receiveloop_design.pu @@ -6,10 +6,19 @@ start repeat : Receive single byte; - if( success ) then (yes) - : Get rest of packet; + if( read successful? ) then (yes) + repeat + : Get rest of packet; + note left: Retry zero byte reads for maximum period \nof **MQTT_RECV_POLLING_TIMEOUT_MS** + repeat while( Received complete packet? ) is ( no ) : Deserialize packet; - : Application callback; + if ( Need to send ACK response? ) then (yes) + repeat + : Send ACK packet; + note left: Retry zero byte sends for maximum period \nof **MQTT_SEND_RETRY_TIMEOUT_MS** + repeat while( Sent complete packet? ) is ( no ) + else (no) + endif else (no) endif