You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Adds doxygen pages detailing the design of the MQTT agent, and its messaging interface. Also adds some notes to improve the documentation of functions, and a missed example code block.
Copy file name to clipboardExpand all lines: docs/doxygen/pages.dox
+219-5Lines changed: 219 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -6,43 +6,139 @@
6
6
The coreMQTT Agent is a thread-safe library to serialize calls to coreMQTT, to be executed by a single thread. It provides APIs for a single, dedicated agent task to process coreMQTT related commands, and the APIs for other tasks to enqueue these commands for processing.
7
7
8
8
@section coreMQTT_brief Why is there a higher level library based on coreMQTT?
9
-
coreMQTT is an MIT licensed open source C MQTT client library for microcontroller and small microprocessor based IoT devices. Its design is intentionally simple to ensure it has no dependency on any other library or operating system, and to better enable static analysis including memory safety proofs. That simplicity and lack of operating system dependency (coreMQTT does not require multithreading at all) means coreMQTT does not build thread safety directly into its implementation. Instead, thread safety must be provided by higher level software. The coreMQTT Agent library is a coreMQTT extension that provides that higher level functionality in the form of an MQTT agent (or MQTT daemon).
9
+
[coreMQTT](@ref mqtt) is an MIT licensed open source C MQTT client library for microcontroller and small microprocessor based IoT devices. Its design is intentionally simple to ensure it has no dependency on any other library or operating system, and to better enable static analysis including memory safety proofs. That simplicity and lack of operating system dependency (coreMQTT does not require multithreading at all) means coreMQTT does not build thread safety directly into its implementation. Instead, thread safety must be provided by higher level software. The coreMQTT Agent library is a coreMQTT extension that provides that higher level functionality in the form of an MQTT agent (or MQTT daemon).
@brief Memory requirements of the MQTT Agent library, including the coreMQTT library.
13
13
14
14
@include{doc} size_table.html
15
15
*/
16
16
17
+
/**
18
+
@page mqtt_agent_design Design
19
+
@brief Architecture of the MQTT Agent library.
20
+
21
+
@section mqtt_agent_task_thread_safety Thread Safe and Unsafe APIs
22
+
23
+
The MQTT Agent APIs are designed to be used by two types of tasks:
24
+
- An MQTT agent task that manages an MQTT connection and calls coreMQTT APIs. The APIs used by this task are not thread safe, and each agent task should use a unique @ref MQTTAgentContext_t (multiple agent tasks may be used to handle multiple simultaneous MQTT connections, but each must have a unique context). This task is expected to invoke @ref MQTTAgent_CommandLoop to process commands from other tasks to call coreMQTT APIs. The APIs for this task are:
25
+
- @ref MQTTAgent_Init
26
+
- @ref MQTTAgent_CommandLoop
27
+
- @ref MQTTAgent_ResumeSession
28
+
- @ref MQTTAgent_CancelAll
29
+
- Application tasks that want to perform MQTT operations with thread safety. These tasks are any task that is <i>not</i> an MQTT agent task. The APIs used by application tasks are thread safe, and send commands that are processed by an MQTT agent task in @ref MQTTAgent_CommandLoop. These APIs can accept several structures used by either the command or completion callback, and these structures MUST remain in scope until the associated command has been completed, including @ref MQTTPublishInfo_t, @ref MQTTAgentSubscribeArgs_t, @ref MQTTAgentConnectArgs_t, and @ref MQTTAgentCommandContext_t. The APIs are asynchronous, so will return as soon as the command has been sent; they will <i>not</i> wait for the command to be processed. These APIs are:
30
+
- @ref MQTTAgent_Publish
31
+
- @ref MQTTAgent_Subscribe
32
+
- @ref MQTTAgent_Unsubscribe
33
+
- @ref MQTTAgent_Ping
34
+
- @ref MQTTAgent_Connect
35
+
- @ref MQTTAgent_Disconnect
36
+
- @ref MQTTAgent_Terminate
37
+
38
+
@section mqtt_agent_interfaces Interfaces and Callbacks
39
+
Similar to coreMQTT, the MQTT Agent library relies on interfaces to dissociate itself from platform specific functionality. Interfaces used by the MQTT Agent library are simply function pointers with expectations of behavior.
40
+
41
+
The MQTT Agent library expects the application to provide implementations for the following interfaces:
42
+
43
+
<table>
44
+
<tr>
45
+
<td><b>Function Pointer</b></td>
46
+
<td><b>Use</b></td>
47
+
</tr>
48
+
<tr>
49
+
<td>@ref MQTTAgentMessageRecv_t</td>
50
+
<td>Receiving commands sent to the agent task.</td>
51
+
</tr>
52
+
<tr>
53
+
<td>@ref MQTTAgentMessageSend_t</td>
54
+
<td>Sending commands to the agent task from the application</td>
55
+
</tr>
56
+
<tr>
57
+
<td>@ref MQTTAgentCommandGet_t</td>
58
+
<td>Allocating storage for a command to be sent to the agent task.</td>
59
+
</tr>
60
+
<tr>
61
+
<td>@ref MQTTAgentCommandRelease_t</td>
62
+
<td>Releasing a command obtained from @ref MQTTAgentCommandGet_t.</td>
63
+
</tr>
64
+
<tr>
65
+
<td>@ref MQTTAgentIncomingPublishCallback_t</td>
66
+
<td>Accepting incoming publish messages, with the possibility of further distributing them to other tasks.</td>
Commands do not have any timeout associated with them. The only way for a task to be aware of a command's completion is through the invocation of an optional @ref MQTTAgentCommandCallback_t completion callback.
72
+
The completion callback will be invoked with an optional @ref MQTTAgentCommandContext_t, which is the incomplete type <b>struct MQTTAgentCommandContext</b>. This type must be defined by the application, and should contain information that would be useful in distinguishing commands.<br>
73
+
<b>Example code:</b>
74
+
@code{c}
75
+
struct MQTTAgentCommandContext
76
+
{
77
+
//Allow the calling thread to view the return code by copying it here.
78
+
MQTTStatus_t returnCode;
79
+
//pthread mutex and condition variables to signal to the thread that created the command.
80
+
pthread_mutex_t lock;
81
+
pthread_cond_t cond;
82
+
};
83
+
@endcode
84
+
<br>
85
+
The completion callback using such a context could be:
The completion callback and completion context are each optional, and passed at time of command creation in the @ref MQTTAgentCommandInfo_t parameter. If a command completion context is passed, it MUST remain in scope until the completion callback has been invoked.
99
+
*/
100
+
17
101
/**
18
102
@page core_mqtt_agent_config Configurations
19
103
@brief Configurations of the MQTT Agent.
20
104
<!-- @par configpagestyle allows the @section titles to be styled according to style.css -->
21
105
@par configpagestyle
22
106
23
-
Configuration settings are C preprocessor constants. They can be set with a `#define` in the config file (**core_mqtt_config.h**) or by using a compiler option such as -D in gcc. The MQTT Agent uses the same configuration file as coreMQTT.
107
+
Configuration settings are C preprocessor constants. They can be set with a `#define` in the config file (**core_mqtt_config.h**) or by using a compiler option such as -D in gcc. The MQTT Agent uses the same configuration file as [coreMQTT](@ref mqtt).
24
108
25
109
@section MQTT_AGENT_MAX_OUTSTANDING_ACKS
26
110
@copydoc MQTT_AGENT_MAX_OUTSTANDING_ACKS
27
111
28
112
@section MQTT_AGENT_MAX_EVENT_QUEUE_WAIT_TIME
29
113
@copydoc MQTT_AGENT_MAX_EVENT_QUEUE_WAIT_TIME
30
114
115
+
@section MQTT_AGENT_FUNCTION_TABLE
116
+
@copydoc MQTT_AGENT_FUNCTION_TABLE
117
+
31
118
*/
32
119
33
120
/**
34
121
@page mqtt_agent_functions Functions
35
-
@brief Primary functions of the MQTT Agent:<br><br>
122
+
@brief Functions of the MQTT Agent library<br><br>
The message interface is a set of APIs to send MQTT Agent commands from application tasks to the MQTT agent task, as well as functions to allocate and release storage for these commands.
194
+
It must be implemented with thread safety, as multiple tasks can send commands concurrently. The message interface is defined in @ref core_mqtt_agent_message_interface.h.<br>
The send and receive functions take in an opaque context @ref MQTTAgentMessageContext_t. The functions above and the context are grouped together in the @ref MQTTAgentMessageInterface_t structure:<br>
@ref MQTTAgentMessageContext_t is the incomplete type <b>struct MQTTAgentMessageContext</b>. The implemented struct MQTTAgentMessageContext must contain all of the information needed to send and receive commands with @ref MQTTAgentMessageSend_t and @ref MQTTAgentMessageRecv_t with thread safety. For example, this may be a handle to a thread safe queue, or a queue along with synchronization primitives. Commands are sent by pointer, so this structure should be able to relay pointers of type [MQTTAgentCommand_t](@ref MQTTAgentCommand).<br><br>
This function is expected to receive a pointer that has been previously sent to the message context, and return in via the <b>pReceivedCommand</b> parameter.
248
+
It will return `true` if the receive was successful, else `false`.<br><br>
0 commit comments