Add links to the MQTT agent in the non-agent mqtt demos (#470)

Add URL file links to the MQTT agent documentation page.
Add comment blocks into each demo that also point toward the MQTT agent documentation to ensure users are aware the agent method exists.

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/Common/main.c

@@ -25,7 +25,23 @@
  */
 
 /***
- * See https://www.FreeRTOS.org/coremqtt for configuration and usage instructions.
+ * See https://www.FreeRTOS.org/coremqtt for configuration and usage instructions,
+ * and https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an alternative
+ * usage model that runs MQTT in an autonomous background agent task.  See the
+ * note below.
+ *
+ * Note: Single Threaded Vs Multi Threaded
+ * There are two coreMQTT usage models, single threaded and multithreaded
+ * (multitasking). Using the MQTT library solely from one thread within an
+ * otherwise multi-threaded application, as the demos in these subdirectories do,
+ * is equivalent to the single threaded use case. Single threaded use cases
+ * require the application writer to make repeated explicit calls into the MQTT
+ * library. Multithreaded use cases can instead execute the MQTT protocol in the
+ * background within an agent (or daemon) task. Executing the MQTT protocol in
+ * an agent task removes the need for the application writer to explicitly
+ * manage any MQTT state or call the MQTT_ProcessLoop() API function. Using an
+ * agent task also enables multiple application tasks to share a single MQTT
+ * connection without the need for synchronization primitives such as mutexes.
  ***/
 
 /* Standard includes. */
@@ -106,7 +122,23 @@ static UBaseType_t ulNextRand;
 int main( void )
 {
     /***
-     * See https://www.FreeRTOS.org/coremqtt for configuration and usage instructions.
+     * See https://www.FreeRTOS.org/coremqtt for configuration and usage instructions,
+     * and https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an alternative
+     * usage model that runs MQTT in an autonomous background agent task.  See the
+     * note below.
+     *
+     * Note: Single Threaded Vs Multi Threaded
+     * There are two coreMQTT usage models, single threaded and multithreaded
+     * (multitasking). Using the MQTT library solely from one thread within an
+     * otherwise multi-threaded application, as the demos in these subdirectories do,
+     * is equivalent to the single threaded use case. Single threaded use cases
+     * require the application writer to make repeated explicit calls into the MQTT
+     * library. Multithreaded use cases can instead execute the MQTT protocol in the
+     * background within an agent (or daemon) task. Executing the MQTT protocol in
+     * an agent task removes the need for the application writer to explicitly
+     * manage any MQTT state or call the MQTT_ProcessLoop() API function. Using an
+     * agent task also enables multiple application tasks to share a single MQTT
+     * connection without the need for synchronization primitives such as mutexes.
      ***/
 
     /* Miscellaneous initialization including preparing the logging and seeding

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/DemoTasks/BasicTLSMQTTExample.c

@@ -37,6 +37,14 @@
  * broker in this example. Define democonfigMQTT_BROKER_ENDPOINT and
  * democonfigROOT_CA_PEM in demo_config.h to establish a server-authenticated
  * connection.
+ *
+ * Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+ * alternative run time model whereby coreMQTT runs in an autonomous
+ * background agent task.  Executing the MQTT protocol in an agent task
+ * removes the need for the application writer to explicitly manage any MQTT
+ * state or call the MQTT_ProcessLoop() API function. Using an agent task
+ * also enables multiple application tasks to more easily share a single
+ * MQTT connection.
  */
 
 /* Standard includes. */
@@ -373,7 +381,15 @@ void vStartSimpleMQTTDemo( void )
 {
     /* This example uses a single application task, which in turn is used to
      * connect, subscribe, publish, unsubscribe, and disconnect from the MQTT
-     * broker. */
+     * broker.
+     *
+     * Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+     * alternative run time model whereby coreMQTT runs in an autonomous
+     * background agent task.  Executing the MQTT protocol in an agent task
+     * removes the need for the application writer to explicitly manage any MQTT
+     * state or call the MQTT_ProcessLoop() API function. Using an agent task
+     * also enables multiple application tasks to more easily share a single
+     * MQTT connection. */
      xTaskCreate( prvMQTTDemoTask,          /* Function that implements the task. */
                  "DemoTask",               /* Text name for the task - only used for debugging. */
                  democonfigDEMO_STACKSIZE, /* Size of stack (in words, not bytes) to allocate for the task. */

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/readme_also_coreMQTT_multithreading_agent.url

@@ -0,0 +1,5 @@
+[{000214A0-0000-0000-C000-000000000046}]
+Prop3=19,11
+[InternetShortcut]
+IDList=
+URL=https://www.freertos.org/mqtt/mqtt-agent-demo.html?

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/DemoTasks/KeepAliveMQTTExample.c

@@ -40,6 +40,14 @@
  * !!! NOTE !!!
  * This MQTT demo does not authenticate the server nor the client.
  * Hence, this demo should not be used as production ready code.
+ *
+ * Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+ * alternative run time model whereby coreMQTT runs in an autonomous
+ * background agent task.  Executing the MQTT protocol in an agent task
+ * removes the need for the application writer to explicitly manage any MQTT
+ * state or call the MQTT_ProcessLoop() API function. Using an agent task
+ * also enables multiple application tasks to more easily share a single
+ * MQTT connection.
  */
 
 /* Standard includes. */
@@ -481,6 +489,13 @@ void vStartSimpleMQTTDemo( void )
 }
 /*-----------------------------------------------------------*/
 
+ /* Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+ * alternative run time model whereby coreMQTT runs in an autonomous
+ * background agent task.  Executing the MQTT protocol in an agent task
+ * removes the need for the application writer to explicitly manage any MQTT
+ * state or call the MQTT_ProcessLoop() API function. Using an agent task
+ * also enables multiple application tasks to more easily share a single
+ * MQTT connection. */
 static void prvMQTTDemoTask( void * pvParameters )
 {
     uint32_t ulTopicCount = 0U;

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/readme_also_coreMQTT_multithreading_agent.url

@@ -0,0 +1,5 @@
+[{000214A0-0000-0000-C000-000000000046}]
+Prop3=19,11
+[InternetShortcut]
+IDList=
+URL=https://www.freertos.org/mqtt/mqtt-agent-demo.html?

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/DemoTasks/MultitaskMQTTExample.c

@@ -28,6 +28,13 @@
  * This demo shows how to use coreMQTT in a multithreaded environment - it does not
  * yet go as far as encapsulating the MQTT library within its own agent (or daemon)
  * task - although the prvCommandLoop() function demonstrates how that might be done.
+ * Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+ * example that does use an agent task.  Executing the MQTT protocol in an agent
+ * task removes the need for the application writer to explicitly manage any MQTT
+ * state or call the MQTT_ProcessLoop() API function. Using an agent task
+ * also enables multiple application tasks to more easily share a single
+ * MQTT connection.
+ *
  * In this task prvCommandLoop() is only executed from a single thread and is the
  * only function that is allowed to use the coreMQTT API directly.  Anything else
  * needing to interact with the coreMQTT API does so by posting commands to
@@ -2098,6 +2105,13 @@ static void prvCleanExistingPersistentSession( void )
 
 /*-----------------------------------------------------------*/
 
+ /* Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+  * alternative run time model whereby coreMQTT runs in an autonomous
+  * background agent task.  Executing the MQTT protocol in an agent task
+  * removes the need for the application writer to explicitly manage any MQTT
+  * state or call the MQTT_ProcessLoop() API function. Using an agent task
+  * also enables multiple application tasks to more easily share a single
+  * MQTT connection. */
 static void prvMQTTDemoTask( void * pvParameters )
 {
     BaseType_t xNetworkStatus = pdFAIL;

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/readme_also_coreMQTT_multithreading_agent.url

@@ -0,0 +1,5 @@
+[{000214A0-0000-0000-C000-000000000046}]
+Prop3=19,11
+[InternetShortcut]
+IDList=
+URL=https://www.freertos.org/mqtt/mqtt-agent-demo.html?

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/DemoTasks/MutualAuthMQTTExample.c

@@ -38,6 +38,14 @@
  * democonfigROOT_CA_PEM, democonfigCLIENT_CERTIFICATE_PEM,
  * and democonfigCLIENT_PRIVATE_KEY_PEM in demo_config.h to establish a
  * mutually authenticated connection.
+ *
+ * Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+ * alternative run time model whereby coreMQTT runs in an autonomous
+ * background agent task.  Executing the MQTT protocol in an agent task
+ * removes the need for the application writer to explicitly manage any MQTT
+ * state or call the MQTT_ProcessLoop() API function. Using an agent task
+ * also enables multiple application tasks to more easily share a single
+ * MQTT connection.
  */
 
 /* Standard includes. */
@@ -462,7 +470,15 @@ void vStartSimpleMQTTDemo( void )
 {
     /* This example uses a single application task, which in turn is used to
      * connect, subscribe, publish, unsubscribe and disconnect from the MQTT
-     * broker. */
+     * broker.
+     *
+     * Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+     * alternative run time model whereby coreMQTT runs in an autonomous
+     * background agent task.  Executing the MQTT protocol in an agent task
+     * removes the need for the application writer to explicitly manage any MQTT
+     * state or call the MQTT_ProcessLoop() API function. Using an agent task
+     * also enables multiple application tasks to more easily share a single
+     * MQTT connection. */
     xTaskCreate( prvMQTTDemoTask,          /* Function that implements the task. */
                  "DemoTask",               /* Text name for the task - only used for debugging. */
                  democonfigDEMO_STACKSIZE, /* Size of stack (in words, not bytes) to allocate for the task. */

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/readme_also_coreMQTT_multithreading_agent.url

@@ -0,0 +1,5 @@
+[{000214A0-0000-0000-C000-000000000046}]
+Prop3=19,11
+[InternetShortcut]
+IDList=
+URL=https://www.freertos.org/mqtt/mqtt-agent-demo.html?

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/DemoTasks/PlaintextMQTTExample.c

@@ -36,6 +36,14 @@
  * !!! NOTE !!!
  * This MQTT demo does not authenticate the server nor the client.
  * Hence, this demo should not be used as production ready code.
+ *
+ * Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+ * alternative run time model whereby coreMQTT runs in an autonomous
+ * background agent task.  Executing the MQTT protocol in an agent task
+ * removes the need for the application writer to explicitly manage any MQTT
+ * state or call the MQTT_ProcessLoop() API function. Using an agent task
+ * also enables multiple application tasks to more easily share a single
+ * MQTT connection.
  */
 
 /* Standard includes. */
@@ -358,7 +366,15 @@ void vStartSimpleMQTTDemo( void )
 {
     /* This example uses a single application task, which in turn is used to
      * connect, subscribe, publish, unsubscribe and disconnect from the MQTT
-     * broker. */
+     * broker.
+     *
+     * Also see https://www.freertos.org/mqtt/mqtt-agent-demo.html? for an
+     * alternative run time model whereby coreMQTT runs in an autonomous
+     * background agent task.  Executing the MQTT protocol in an agent task
+     * removes the need for the application writer to explicitly manage any MQTT
+     * state or call the MQTT_ProcessLoop() API function. Using an agent task
+     * also enables multiple application tasks to more easily share a single
+     * MQTT connection.*/
     xTaskCreate( prvMQTTDemoTask,          /* Function that implements the task. */
                  "DemoTask",               /* Text name for the task - only used for debugging. */
                  democonfigDEMO_STACKSIZE, /* Size of stack (in words, not bytes) to allocate for the task. */

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/readme_also_coreMQTT_multithreading_agent.url

@@ -0,0 +1,5 @@
+[{000214A0-0000-0000-C000-000000000046}]
+Prop3=19,11
+[InternetShortcut]
+IDList=
+URL=https://www.freertos.org/mqtt/mqtt-agent-demo.html?

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Serializer/readme_coreMQTT_multithreading_agent.url

@@ -0,0 +1,5 @@
+[{000214A0-0000-0000-C000-000000000046}]
+Prop3=19,11
+[InternetShortcut]
+IDList=
+URL=https://www.freertos.org/mqtt/mqtt-agent-demo.html?

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/readme_also_coreMQTT_multithreading_agent.url

@@ -0,0 +1,5 @@
+[{000214A0-0000-0000-C000-000000000046}]
+Prop3=19,11
+[InternetShortcut]
+IDList=
+URL=https://www.freertos.org/mqtt/mqtt-agent-demo.html?

FreeRTOS-Plus/Source/Application-Protocols/coreMQTT

@@ -1 +1 @@
-Subproject commit cf7406a98c00d27b519797df6932dc3b7f74cc5d
+Subproject commit 93c15bdab832f0a0aa3b6deb06dd19b0d5227133

FreeRTOS-Plus/Source/FreeRTOS-Plus-TCP

@@ -1 +1 @@
-Subproject commit 51590f627e9fe830fabd51958df250181f2712d2
+Subproject commit 21d3a247ff09445d10f6e6745f8dc055c46c29af

FreeRTOS-Plus/Source/coreJSON

@@ -1 +1 @@
-Subproject commit c3ed2a23a64390178f6332589aac6994cb944f48
+Subproject commit 5bfadf5f86a038986ebdf7114939d73de2681f7f

FreeRTOS-Plus/Source/corePKCS11

@@ -1 +1 @@
-Subproject commit d35a8f041fa335a1661ad0a523c44f4c967fa492
+Subproject commit efc4b34b03f1aef39af7fb771c46a541f0eeb2e3

FreeRTOS/Source

@@ -1 +1 @@
-Subproject commit 47338393f1f79558f6144213409f09f81d7c4837
+Subproject commit 50a23218381574f2ba314109691e1de4f8456684