generate PINGREQ packets on idle input or output.

docs/doxygen/include/size_table.md

@@ -9,8 +9,8 @@
     </tr>
     <tr>
         <td>core_mqtt.c</td>
-        <td><center>3.0K</center></td>
-        <td><center>2.6K</center></td>
+        <td><center>3.1K</center></td>
+        <td><center>2.7K</center></td>
     </tr>
     <tr>
         <td>core_mqtt_state.c</td>
@@ -24,7 +24,7 @@
     </tr>
     <tr>
         <td><b>Total estimates</b></td>
-        <td><b><center>6.9K</center></b></td>
-        <td><b><center>5.7K</center></b></td>
+        <td><b><center>7.0K</center></b></td>
+        <td><b><center>5.8K</center></b></td>
     </tr>
 </table>

docs/doxygen/pages.dox

@@ -133,7 +133,7 @@ In this library, @ref mqtt_processloop_function handles sending of PINGREQs and
 The standard does not specify the time duration within which the server has to respond to a ping request, noting only a "reasonable amount of time". If the response to a ping request is not received within @ref MQTT_PINGRESP_TIMEOUT_MS, this library assumes that the connection is dead.
 
 If @ref mqtt_receiveloop_function is used instead of @ref mqtt_processloop_function, then no ping requests are sent. The application must ensure the connection does not remain idle for more than the keep-alive interval by calling @ref mqtt_ping_function to send ping requests.
-The timestamp in @ref MQTTContext_t.lastPacketTime indicates when a packet was last sent by the library.
+The timestamp in @ref MQTTContext_t.lastPacketTxTime indicates when a packet was last sent by the library.
 
 Sending any ping request sets the @ref MQTTContext_t.waitingForPingResp flag. This flag is cleared by @ref mqtt_processloop_function when a ping response is received. If @ref mqtt_receiveloop_function is used instead, then this flag must be cleared manually by the application's callback.
 */

lexicon.txt

@@ -118,7 +118,7 @@ iso
 keepaliveintervalsec
 keepalivems
 keepaliveseconds
-lastpackettime
+lastpackettxtime
 linux
 logdebug
 logerror
@@ -318,6 +318,7 @@ resending
 reservestate
 responsecode
 rm
+rx
 sdk
 searchstates
 sendpacket

source/core_mqtt.c

@@ -662,7 +662,7 @@ static int32_t sendPacket( MQTTContext_t * pContext,
     /* Update time of last transmission if the entire packet is successfully sent. */
     if( totalBytesSent > 0 )
     {
-        pContext->lastPacketTime = lastSendTimeMs;
+        pContext->lastPacketTxTime = lastSendTimeMs;
         LogDebug( ( "Successfully sent packet at time %lu.",
                     ( unsigned long ) lastSendTimeMs ) );
     }
@@ -1002,32 +1002,42 @@ static MQTTStatus_t sendPublishAcks( MQTTContext_t * pContext,
 static MQTTStatus_t handleKeepAlive( MQTTContext_t * pContext )
 {
     MQTTStatus_t status = MQTTSuccess;
-    uint32_t now = 0U, keepAliveMs = 0U;
+    uint32_t now = 0U, packetTxTimeoutMs = 0U;
 
     assert( pContext != NULL );
     assert( pContext->getTime != NULL );
 
     now = pContext->getTime();
-    keepAliveMs = 1000U * ( uint32_t ) pContext->keepAliveIntervalSec;
+
+    packetTxTimeoutMs = 1000U * ( uint32_t ) pContext->keepAliveIntervalSec;
+
+    if( PACKET_TX_TIMEOUT_MS < packetTxTimeoutMs )
+    {
+        packetTxTimeoutMs = PACKET_TX_TIMEOUT_MS;
+    }
 
     /* If keep alive interval is 0, it is disabled. */
-    if( keepAliveMs != 0U )
+    if( pContext->waitingForPingResp == true )
     {
-        if( pContext->waitingForPingResp == true )
+        /* Has time expired? */
+        if( calculateElapsedTime( now, pContext->pingReqSendTimeMs ) >
+            MQTT_PINGRESP_TIMEOUT_MS )
         {
-            /* Has time expired? */
-            if( calculateElapsedTime( now, pContext->pingReqSendTimeMs ) >
-                MQTT_PINGRESP_TIMEOUT_MS )
-            {
-                status = MQTTKeepAliveTimeout;
-            }
+            status = MQTTKeepAliveTimeout;
+        }
+    }
+    else
+    {
+        if( ( packetTxTimeoutMs != 0U ) && ( calculateElapsedTime( now, pContext->lastPacketTxTime ) >= packetTxTimeoutMs ) )
+        {
+            status = MQTT_Ping( pContext );
+        }
+        else if( ( PACKET_RX_TIMEOUT_MS != 0U ) && ( calculateElapsedTime( now, pContext->lastPacketRxTime ) >= PACKET_RX_TIMEOUT_MS ) )
+        {
+            status = MQTT_Ping( pContext );
         }
         else
         {
-            if( calculateElapsedTime( now, pContext->lastPacketTime ) > keepAliveMs )
-            {
-                status = MQTT_Ping( pContext );
-            }
         }
     }
 
@@ -1340,6 +1350,7 @@ static MQTTStatus_t receiveSingleIteration( MQTTContext_t * pContext,
     if( status == MQTTSuccess )
     {
         incomingPacket.pRemainingData = pContext->networkBuffer.pBuffer;
+        pContext->lastPacketRxTime = pContext->getTime();
 
         /* PUBLISH packets allow flags in the lower four bits. For other
          * packet types, they are reserved. */
@@ -2037,7 +2048,7 @@ MQTTStatus_t MQTT_Ping( MQTTContext_t * pContext )
         }
         else
         {
-            pContext->pingReqSendTimeMs = pContext->lastPacketTime;
+            pContext->pingReqSendTimeMs = pContext->lastPacketTxTime;
             pContext->waitingForPingResp = true;
             LogDebug( ( "Sent %ld bytes of PINGREQ packet.",
                         ( long int ) bytesSent ) );

source/include/core_mqtt.h

@@ -37,7 +37,7 @@
  * without a custom config. If a custom config is provided, the
  * MQTT_DO_NOT_USE_CUSTOM_CONFIG macro should not be defined. */
 #ifndef MQTT_DO_NOT_USE_CUSTOM_CONFIG
-    /* Include custom config file before other headers. */
+/* Include custom config file before other headers. */
     #include "core_mqtt_config.h"
 #endif
 
@@ -210,7 +210,12 @@ typedef struct MQTTContext
     /**
      * @brief Timestamp of the last packet sent by the library.
      */
-    uint32_t lastPacketTime;
+    uint32_t lastPacketTxTime;
+
+    /**
+     * @brief Timestamp of the last packet received by the library.
+     */
+    uint32_t lastPacketRxTime;
 
     /**
      * @brief Whether the library sent a packet during a call of #MQTT_ProcessLoop or
@@ -720,7 +725,7 @@ MQTTStatus_t MQTT_ProcessLoop( MQTTContext_t * pContext,
  *      {
  *          // Since this function does not send pings, the application may need
  *          // to in order to comply with keep alive.
- *          if( ( pContext->getTime() - pContext->lastPacketTime ) > keepAliveMs )
+ *          if( ( pContext->getTime() - pContext->lastPacketTxTime ) > keepAliveMs )
  *          {
  *              status = MQTT_Ping( pContext );
  *          }

source/include/core_mqtt_config_defaults.h

@@ -78,7 +78,7 @@
  * <b>Default value:</b> `10`
  */
 #ifndef MQTT_STATE_ARRAY_MAX_COUNT
-    /* Default value for the maximum acknowledgment pending PUBLISH messages. */
+/* Default value for the maximum acknowledgment pending PUBLISH messages. */
     #define MQTT_STATE_ARRAY_MAX_COUNT    ( 10U )
 #endif
 
@@ -95,7 +95,7 @@
  * <b>Default value:</b> `5`
  */
 #ifndef MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT
-    /* Default value for the CONNACK receive retries. */
+/* Default value for the CONNACK receive retries. */
     #define MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT    ( 5U )
 #endif
 
@@ -119,10 +119,36 @@
  * <b>Default value:</b> `5000`
  */
 #ifndef MQTT_PINGRESP_TIMEOUT_MS
-    /* Wait 5 seconds by default for a ping response. */
+/* Wait 5 seconds by default for a ping response. */
     #define MQTT_PINGRESP_TIMEOUT_MS    ( 5000U )
 #endif
 
+/**
+ * @brief Maximum number of milliseconds of TX inactivity to wait
+ * before initiating a PINGREQ
+ *
+ * @note If this value is less than the keep alive interval than
+ * it will be used instead.
+ *
+ * <b>Possible values:</b> Any positive integer up to SIZE_MAX. <br>
+ * <b>Default value:</b> '30000'
+ */
+#ifndef PACKET_TX_TIMEOUT_MS
+    #define PACKET_TX_TIMEOUT_MS    ( 30000U )
+#endif
+
+/**
+ * @brief Maximum number of milliseconds of RX inactivity to wait
+ * before initiating a PINGREQ
+ *
+ * <b>Possible values:</b> Any positive integer up to SIZE_MAX. <br>
+ * <b>Default value:</b> '30000'
+ *
+ */
+#ifndef PACKET_RX_TIMEOUT_MS
+    #define PACKET_RX_TIMEOUT_MS    ( 30000U )
+#endif
+
 /**
  * @brief The maximum duration between non-empty network reads while
  * receiving an MQTT packet via the #MQTT_ProcessLoop or #MQTT_ReceiveLoop

test/unit-test/core_mqtt_utest.c

@@ -100,11 +100,11 @@
  * that the API can support normal behavior even if the timer
  * overflows.
  *
- * @note Currently, there are 5 calls within a single iteration.
+ * @note Currently, there are 6 calls within a single iteration.
  * This can change when the implementation changes which would be
  * caught through unit test failure.
  */
-#define MQTT_TIMER_CALLS_PER_ITERATION         ( 5 )
+#define MQTT_TIMER_CALLS_PER_ITERATION         ( 6 )
 
 /**
  * @brief Timeout for the timer overflow test.
@@ -465,6 +465,7 @@ static void expectProcessLoopCalls( MQTTContext_t * const pContext,
     MQTTStatus_t processLoopStatus = pExpectParams->processLoopStatus;
     bool incomingPublish = pExpectParams->incomingPublish;
     MQTTPublishInfo_t * pPubInfo = pExpectParams->pPubInfo;
+    uint32_t packetTxTimeoutMs = 0U;
 
     /* Modify incoming packet depending on type to be tested. */
     incomingPacket.type = currentPacketType;
@@ -489,14 +490,25 @@ static void expectProcessLoopCalls( MQTTContext_t * const pContext,
     /* When no data is available, the process loop tries to send a PINGREQ. */
     if( modifyIncomingPacketStatus == MQTTNoDataAvailable )
     {
-        if( ( pContext->waitingForPingResp == false ) &&
-            ( pContext->keepAliveIntervalSec != 0U ) &&
-            ( ( globalEntryTime - pContext->lastPacketTime ) > ( 1000U * pContext->keepAliveIntervalSec ) ) )
+        packetTxTimeoutMs = 1000U * ( uint32_t ) pContext->keepAliveIntervalSec;
+
+        if( PACKET_TX_TIMEOUT_MS < packetTxTimeoutMs )
         {
-            MQTT_GetPingreqPacketSize_ExpectAnyArgsAndReturn( MQTTSuccess );
-            /* Replace pointer parameter being passed to the method. */
-            MQTT_GetPingreqPacketSize_ReturnThruPtr_pPacketSize( &pingreqSize );
-            MQTT_SerializePingreq_ExpectAnyArgsAndReturn( serializeStatus );
+            packetTxTimeoutMs = PACKET_TX_TIMEOUT_MS;
+        }
+
+        if( pContext->waitingForPingResp == false )
+        {
+            if( ( ( packetTxTimeoutMs != 0U ) &&
+                  ( ( globalEntryTime - pContext->lastPacketTxTime ) >= packetTxTimeoutMs ) ) ||
+                ( ( PACKET_RX_TIMEOUT_MS != 0U ) &&
+                  ( ( globalEntryTime - pContext->lastPacketRxTime ) >= PACKET_RX_TIMEOUT_MS ) ) )
+            {
+                MQTT_GetPingreqPacketSize_ExpectAnyArgsAndReturn( MQTTSuccess );
+                /* Replace pointer parameter being passed to the method. */
+                MQTT_GetPingreqPacketSize_ReturnThruPtr_pPacketSize( &pingreqSize );
+                MQTT_SerializePingreq_ExpectAnyArgsAndReturn( serializeStatus );
+            }
         }
 
         expectMoreCalls = false;
@@ -1934,7 +1946,7 @@ void test_MQTT_ProcessLoop_handleKeepAlive_Happy_Paths( void )
     mqttStatus = MQTT_Init( &context, &transport, getTime, eventCallback, &networkBuffer );
     TEST_ASSERT_EQUAL( MQTTSuccess, mqttStatus );
     context.keepAliveIntervalSec = MQTT_SAMPLE_KEEPALIVE_INTERVAL_S;
-    context.lastPacketTime = getTime();
+    context.lastPacketTxTime = getTime();
     /* Set expected return values in the loop. All success. */
     resetProcessLoopParams( &expectParams );
     expectProcessLoopCalls( &context, &expectParams );
@@ -1944,7 +1956,7 @@ void test_MQTT_ProcessLoop_handleKeepAlive_Happy_Paths( void )
     TEST_ASSERT_EQUAL( MQTTSuccess, mqttStatus );
     context.waitingForPingResp = true;
     context.keepAliveIntervalSec = MQTT_SAMPLE_KEEPALIVE_INTERVAL_S;
-    context.lastPacketTime = MQTT_ONE_SECOND_TO_MS;
+    context.lastPacketTxTime = MQTT_ONE_SECOND_TO_MS;
     context.pingReqSendTimeMs = MQTT_ONE_SECOND_TO_MS;
     /* Set expected return values in the loop. All success. */
     resetProcessLoopParams( &expectParams );
@@ -1955,7 +1967,7 @@ void test_MQTT_ProcessLoop_handleKeepAlive_Happy_Paths( void )
     TEST_ASSERT_EQUAL( MQTTSuccess, mqttStatus );
     context.waitingForPingResp = false;
     context.keepAliveIntervalSec = MQTT_SAMPLE_KEEPALIVE_INTERVAL_S;
-    context.lastPacketTime = 0;
+    context.lastPacketTxTime = 0;
     /* Set expected return values in the loop. All success. */
     resetProcessLoopParams( &expectParams );
     expectProcessLoopCalls( &context, &expectParams );
@@ -1983,13 +1995,33 @@ void test_MQTT_ProcessLoop_handleKeepAlive_Error_Paths( void )
     mqttStatus = MQTT_Init( &context, &transport, getTime, eventCallback, &networkBuffer );
     TEST_ASSERT_EQUAL( MQTTSuccess, mqttStatus );
     context.keepAliveIntervalSec = MQTT_SAMPLE_KEEPALIVE_INTERVAL_S;
-    context.lastPacketTime = 0;
+    context.lastPacketTxTime = 0;
+    context.lastPacketRxTime = 0;
     context.pingReqSendTimeMs = 0;
     context.waitingForPingResp = true;
     /* Set expected return values in the loop. */
     resetProcessLoopParams( &expectParams );
     expectParams.processLoopStatus = MQTTKeepAliveTimeout;
     expectProcessLoopCalls( &context, &expectParams );
+
+    context.keepAliveIntervalSec = PACKET_TX_TIMEOUT_MS + 1;
+    context.lastPacketTxTime = 0;
+    context.lastPacketRxTime = 0;
+    context.pingReqSendTimeMs = 0;
+    context.waitingForPingResp = false;
+    /* Set expected return values in the loop. */
+    resetProcessLoopParams( &expectParams );
+    expectProcessLoopCalls( &context, &expectParams );
+
+    globalEntryTime = PACKET_RX_TIMEOUT_MS + 1;
+    context.keepAliveIntervalSec = 0;
+    context.lastPacketTxTime = 0;
+    context.lastPacketRxTime = 0;
+    context.pingReqSendTimeMs = 0;
+    context.waitingForPingResp = false;
+    /* Set expected return values in the loop. */
+    resetProcessLoopParams( &expectParams );
+    expectProcessLoopCalls( &context, &expectParams );
 }
 
 /**
@@ -2391,7 +2423,7 @@ void test_MQTT_Ping_happy_path( void )
     mqttStatus = MQTT_Ping( &context );
     TEST_ASSERT_EQUAL( MQTTSuccess, mqttStatus );
 
-    TEST_ASSERT_EQUAL( context.lastPacketTime, context.pingReqSendTimeMs );
+    TEST_ASSERT_EQUAL( context.lastPacketTxTime, context.pingReqSendTimeMs );
     TEST_ASSERT_TRUE( context.waitingForPingResp );
 }