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 index cf7406a98..93c15bdab 160000 --- a/FreeRTOS-Plus/Source/Application-Protocols/coreMQTT +++ b/FreeRTOS-Plus/Source/Application-Protocols/coreMQTT @@ -1 +1 @@ -Subproject commit cf7406a98c00d27b519797df6932dc3b7f74cc5d +Subproject commit 93c15bdab832f0a0aa3b6deb06dd19b0d5227133 diff --git a/FreeRTOS-Plus/Source/FreeRTOS-Plus-TCP b/FreeRTOS-Plus/Source/FreeRTOS-Plus-TCP index 51590f627..21d3a247f 160000 --- a/FreeRTOS-Plus/Source/FreeRTOS-Plus-TCP +++ b/FreeRTOS-Plus/Source/FreeRTOS-Plus-TCP @@ -1 +1 @@ -Subproject commit 51590f627e9fe830fabd51958df250181f2712d2 +Subproject commit 21d3a247ff09445d10f6e6745f8dc055c46c29af diff --git a/FreeRTOS-Plus/Source/coreJSON b/FreeRTOS-Plus/Source/coreJSON index c3ed2a23a..5bfadf5f8 160000 --- a/FreeRTOS-Plus/Source/coreJSON +++ b/FreeRTOS-Plus/Source/coreJSON @@ -1 +1 @@ -Subproject commit c3ed2a23a64390178f6332589aac6994cb944f48 +Subproject commit 5bfadf5f86a038986ebdf7114939d73de2681f7f diff --git a/FreeRTOS-Plus/Source/corePKCS11 b/FreeRTOS-Plus/Source/corePKCS11 index d35a8f041..efc4b34b0 160000 --- a/FreeRTOS-Plus/Source/corePKCS11 +++ b/FreeRTOS-Plus/Source/corePKCS11 @@ -1 +1 @@ -Subproject commit d35a8f041fa335a1661ad0a523c44f4c967fa492 +Subproject commit efc4b34b03f1aef39af7fb771c46a541f0eeb2e3 diff --git a/FreeRTOS/Source b/FreeRTOS/Source index 47338393f..50a232183 160000 --- a/FreeRTOS/Source +++ b/FreeRTOS/Source @@ -1 +1 @@ -Subproject commit 47338393f1f79558f6144213409f09f81d7c4837 +Subproject commit 50a23218381574f2ba314109691e1de4f8456684