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.

18 files changed, 160 insertions, 16 deletions

diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/Common/main.c b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/Common/main.c
index 27e775d91..5e22636db 100644
--- a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/Common/main.c
+++ b/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
diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/DemoTasks/BasicTLSMQTTExample.c b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/DemoTasks/BasicTLSMQTTExample.c
index 1ceaf91ba..e886a9f34 100644
--- a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/DemoTasks/BasicTLSMQTTExample.c
+++ b/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. */
@@ -185,8 +193,8 @@
 
 /*-----------------------------------------------------------*/
 
-/** 
- * @brief Each compilation unit that consumes the NetworkContext must define it. 
+/**
+ * @brief Each compilation unit that consumes the NetworkContext must define it.
  * It should contain a single pointer to the type of your desired transport.
  * When using multiple transports in the same compilation unit, define this pointer as void *.
  *
@@ -373,8 +381,16 @@ 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. */
-    xTaskCreate( prvMQTTDemoTask,          /* Function that implements the task. */
+     * 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. */
                  NULL,                     /* Task parameter - not used in this case. */
diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/readme_also_coreMQTT_multithreading_agent.url b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/readme_also_coreMQTT_multithreading_agent.url
new file mode 100644
index 000000000..d081119d0
--- /dev/null
+++ b/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?
diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/DemoTasks/KeepAliveMQTTExample.c b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/DemoTasks/KeepAliveMQTTExample.c
index 415039243..a0b8230ef 100644
--- a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/DemoTasks/KeepAliveMQTTExample.c
+++ b/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. */
@@ -207,8 +215,8 @@
 
 /*-----------------------------------------------------------*/
 
-/** 
- * @brief Each compilation unit that consumes the NetworkContext must define it. 
+/**
+ * @brief Each compilation unit that consumes the NetworkContext must define it.
  * It should contain a single pointer to the type of your desired transport.
  * When using multiple transports in the same compilation unit, define this pointer as void *.
  *
@@ -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;
diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/readme_also_coreMQTT_multithreading_agent.url b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/readme_also_coreMQTT_multithreading_agent.url
new file mode 100644
index 000000000..d081119d0
--- /dev/null
+++ b/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?
diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/DemoTasks/MultitaskMQTTExample.c b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/DemoTasks/MultitaskMQTTExample.c
index 6ffc1fe6c..f70f18be1 100644
--- a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/DemoTasks/MultitaskMQTTExample.c
+++ b/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
@@ -375,8 +382,8 @@ typedef struct publishElement
 
 /*-----------------------------------------------------------*/
 
-/** 
- * @brief Each compilation unit that consumes the NetworkContext must define it. 
+/**
+ * @brief Each compilation unit that consumes the NetworkContext must define it.
  * It should contain a single pointer to the type of your desired transport.
  * When using multiple transports in the same compilation unit, define this pointer as void *.
  *
@@ -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;
diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/readme_also_coreMQTT_multithreading_agent.url b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/readme_also_coreMQTT_multithreading_agent.url
new file mode 100644
index 000000000..d081119d0
--- /dev/null
+++ b/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?
diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/DemoTasks/MutualAuthMQTTExample.c b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/DemoTasks/MutualAuthMQTTExample.c
index 5d42b5b5f..2c99366ca 100644
--- a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/DemoTasks/MutualAuthMQTTExample.c
+++ b/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. */
@@ -274,8 +282,8 @@
 
 /*-----------------------------------------------------------*/
 
-/** 
- * @brief Each compilation unit that consumes the NetworkContext must define it. 
+/**
+ * @brief Each compilation unit that consumes the NetworkContext must define it.
  * It should contain a single pointer to the type of your desired transport.
  * When using multiple transports in the same compilation unit, define this pointer as void *.
  *
@@ -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. */
diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/readme_also_coreMQTT_multithreading_agent.url b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/readme_also_coreMQTT_multithreading_agent.url
new file mode 100644
index 000000000..d081119d0
--- /dev/null
+++ b/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?
diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/DemoTasks/PlaintextMQTTExample.c b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/DemoTasks/PlaintextMQTTExample.c
index a3c7a4330..47b3cdf4f 100644
--- a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/DemoTasks/PlaintextMQTTExample.c
+++ b/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. */
@@ -176,8 +184,8 @@
 
 /*-----------------------------------------------------------*/
 
-/** 
- * @brief Each compilation unit that consumes the NetworkContext must define it. 
+/**
+ * @brief Each compilation unit that consumes the NetworkContext must define it.
  * It should contain a single pointer to the type of your desired transport.
  * When using multiple transports in the same compilation unit, define this pointer as void *.
  *
@@ -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. */
diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/readme_also_coreMQTT_multithreading_agent.url b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/readme_also_coreMQTT_multithreading_agent.url
new file mode 100644
index 000000000..d081119d0
--- /dev/null
+++ b/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?
diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Serializer/readme_coreMQTT_multithreading_agent.url b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Serializer/readme_coreMQTT_multithreading_agent.url
new file mode 100644
index 000000000..d081119d0
--- /dev/null
+++ b/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?
diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/readme_also_coreMQTT_multithreading_agent.url b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/readme_also_coreMQTT_multithreading_agent.url
new file mode 100644
index 000000000..d081119d0
--- /dev/null
+++ b/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?
diff --git a/FreeRTOS-Plus/Source/Application-Protocols/coreMQTT b/FreeRTOS-Plus/Source/Application-Protocols/coreMQTT
-Subproject cf7406a98c00d27b519797df6932dc3b7f74cc5
+Subproject 93c15bdab832f0a0aa3b6deb06dd19b0d522713
diff --git a/FreeRTOS-Plus/Source/FreeRTOS-Plus-TCP b/FreeRTOS-Plus/Source/FreeRTOS-Plus-TCP
-Subproject 51590f627e9fe830fabd51958df250181f2712d
+Subproject 21d3a247ff09445d10f6e6745f8dc055c46c29a
diff --git a/FreeRTOS-Plus/Source/coreJSON b/FreeRTOS-Plus/Source/coreJSON
-Subproject c3ed2a23a64390178f6332589aac6994cb944f4
+Subproject 5bfadf5f86a038986ebdf7114939d73de2681f7
diff --git a/FreeRTOS-Plus/Source/corePKCS11 b/FreeRTOS-Plus/Source/corePKCS11
-Subproject d35a8f041fa335a1661ad0a523c44f4c967fa49
+Subproject efc4b34b03f1aef39af7fb771c46a541f0eeb2e
diff --git a/FreeRTOS/Source b/FreeRTOS/Source
-Subproject 47338393f1f79558f6144213409f09f81d7c483
+Subproject 50a23218381574f2ba314109691e1de4f845668