1The subdirectories of this directory contain multiple examples that demonstrate
2coreMQTT using in both single and multi-threaded scenarios, as well as with
3both plain text and authenticated and encrypted network interfaces.
4
5The multi threaded example creates an MQTT agent (or daemon task).  It is thread
6safe because only the agent task is allowed to access the coreMQTT API - hence
7the API is only accessed from one FreeRTOS task.  Other tasks and interrupts
8needing to interact with the MQTT agent do so through a thread safe queue.
9We are generalising this technique for future coreMQTT releases, which will have
10a re-usable agent component.
11
12! Plain text examples are for ease of evaluation only - product devices should
13! always use authenticated and encrypted communication.  Never send private or
14! sensitive data on an unencrypted connection.
15
16
17In MQTT demos, for each iteration we send 3 QoS2 MQTT Publish messages and receive
183 QoS2 MQTT Publish messages because we are subscribed to the same topics we
19publish on. Each QoS2 MQTT publish message results in total 4 MQTT packets
20being exchanged between the device and the broker. For example, the following
21MQTT packets are exchanged between the device and the broker when the device
22sends a QoS2 MQTT Publish message:
23
24   Device                   Broker
25      |                         |
26      |      Publish QoS2       |
27      +------------------------>|
28      |        PUBREC           |
29      |<------------------------+
30      |        PUBREL           |
31      +------------------------>|
32      |       PUBCOMP           |
33      |<------------------------+
34      |                         |
35
36The coreMQTT library keeps track of the in-flight publish messages (i.e. the
37publish messages for which the above 4 packets sequence is not complete) in 2
38application supplied arrays - pOutgoingPublishRecords and pIncomingPublishRecords
39in this demo. We need to set the value of mqttexamplePROCESS_LOOP_TIMEOUT_MS to
40ensure that we can keep up with the incoming MQTT packets. We did some experiments
41to find the optimal value of mqttexamplePROCESS_LOOP_TIMEOUT_MS. The following
42table lists the results of our experiments:
43
44 +------------------------------------+-------------+----------------------------------------------------+
45  | mqttexamplePROCESS_LOOP_TIMEOUT_MS | Iteration # | No. of pending messages in pOutgoingPublishRecords |
46  +------------------------------------+-------------+----------------------------------------------------+
47  |               500                  | 0           | 0                                                  |
48  +                                    +-------------+----------------------------------------------------+
49  |                                    | 1           | 3                                                  |
50  +                                    +-------------+----------------------------------------------------+
51  |                                    | 2           | 3                                                  |
52  +                                    +-------------+----------------------------------------------------+
53  |                                    | 3           | 6                                                  |
54  +                                    +-------------+----------------------------------------------------+
55  |                                    | 4           | 9                                                  |
56  +------------------------------------+-------------+----------------------------------------------------+
57  |              1000                  | 0           | 0                                                  |
58  +                                    +-------------+----------------------------------------------------+
59  |                                    | 1           | 1                                                  |
60  +                                    +-------------+----------------------------------------------------+
61  |                                    | 2           | 3                                                  |
62  +                                    +-------------+----------------------------------------------------+
63  |                                    | 3           | 4                                                  |
64  +                                    +-------------+----------------------------------------------------+
65  |                                    | 4           | 6                                                  |
66  +                                    +-------------+----------------------------------------------------+
67  |                                    | 5           | 7                                                  |
68  +                                    +-------------+----------------------------------------------------+
69  |                                    | 6           | 7                                                  |
70  +------------------------------------+-------------+----------------------------------------------------+
71  |              1500                  | 0           | 0                                                  |
72  +                                    +-------------+----------------------------------------------------+
73  |                                    | 1           | 0                                                  |
74  +                                    +-------------+----------------------------------------------------+
75  |                                    | 2           | 1                                                  |
76  +                                    +-------------+----------------------------------------------------+
77  |                                    | 3           | 2                                                  |
78  +                                    +-------------+----------------------------------------------------+
79  |                                    | 4           | 3                                                  |
80  +                                    +-------------+----------------------------------------------------+
81  |                                    | 5           | 3                                                  |
82  +                                    +-------------+----------------------------------------------------+
83  |                                    | 6           | 0                                                  |
84  +------------------------------------+-------------+----------------------------------------------------+
85  |              2000                  | 0           | 0                                                  |
86  +                                    +-------------+----------------------------------------------------+
87  |                                    | 1           | 0                                                  |
88  +                                    +-------------+----------------------------------------------------+
89  |                                    | 2           | 0                                                  |
90  +                                    +-------------+----------------------------------------------------+
91  |                                    | 3           | 0                                                  |
92  +                                    +-------------+----------------------------------------------------+
93  |                                    | 4           | 0                                                  |
94  +                                    +-------------+----------------------------------------------------+
95  |                                    | 5           | 0                                                  |
96  +                                    +-------------+----------------------------------------------------+
97  |                                    | 6           | 0                                                  |
98  +------------------------------------+-------------+----------------------------------------------------+
99
100As clear from the above table, with the value of mqttexamplePROCESS_LOOP_TIMEOUT_MS
101set to 2000, we are able to keep up with the incoming MQTT packets every iteration.
102mqttexamplePROCESS_LOOP_TIMEOUT_MS can be updated according to the requirements.
103
104