feat(mosq): Add API docs, memory consideration and tests

Author: david-cermak

components/mosquitto/Doxyfile

@@ -0,0 +1,25 @@
+# Set this to the include directory of your component
+INPUT = port/include
+STRIP_FROM_PATH = ./port/include
+
+# Output goes into doxygen directory, which is added to gitignore
+OUTPUT_DIRECTORY = doxygen
+
+# Warning-related settings, it's recommended to keep them enabled
+WARN_AS_ERROR = YES
+
+# Other common settings
+RECURSIVE = YES
+FULL_PATH_NAMES = YES
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             = $(ENV_DOXYGEN_DEFINES)
+HAVE_DOT = NO
+GENERATE_XML    = YES
+XML_OUTPUT      = xml
+GENERATE_HTML   = NO
+HAVE_DOT        = NO
+GENERATE_LATEX  = NO
+QUIET = YES
+MARKDOWN_SUPPORT = YES

components/mosquitto/README.md

@@ -1,3 +1,32 @@
-# ESP32 Mosquitto port (mosq)
+# ESP32 Mosquitto Port
 
-This is a simplified port of the mosquitto broker running on ESP32. It support only a single listener and TCP transport only
+This is a lightweight port of the Mosquitto broker designed to run on the ESP32. It currently supports a single listener and TCP transport only.
+
+## Supported Options
+
+The Espressif port supports a limited set of options (with plans to add more in future releases). These options can be configured through a structure passed to the `mosq_broker_start()` function. For detailed information on available configuration options, refer to the [API documentation](api.md).
+
+## API
+
+### Starting the Broker
+
+To start the broker, call the `mosq_broker_start()` function with a properly configured settings structure. The broker operates in the context of the calling task and does not create a separate task.
+
+It's recommended to analyze the stack size needed for the task, but in general, the broker requires at least 4 kB of stack size.
+
+```c
+mosq_broker_start(&config);
+```
+
+## Memory Footprint Considerations
+
+The broker primarily uses the heap for internal data, with minimal use of static/BSS memory. It consumes approximately 60 kB of program memory.
+
+- **Initial Memory Usage**: ~2 kB of heap on startup
+- **Per Client Memory Usage**: ~4 kB of heap for each connected client
+
+When using the broker with multiple clients, ensure sufficient heap space is available to handle scenarios where clients disconnect abruptly and reconnect. In cases of clean disconnections, the broker releases the memory immediately. However, when a client loses connection abruptly, the broker retains its connection information for some time before eventually freeing this memory. If the client reconnects during this period, an additional 4 kB of heap is allocated for the new connection while the memory for the previous connection is still being retained. Therefore, extra heap space is necessary to manage these abrupt reconnections smoothly.
+
+## Testing
+
+Extensive long-term tests have been conducted with the broker handling 5 clients simultaneously. Each client publishes messages every second to a different topic, while all clients subscribe to all topics. The test also included abrupt disconnections, where clients were suspended and reconnected after 10 seconds, to simulate real-world network instability.

components/mosquitto/api.md

@@ -0,0 +1,65 @@
+# API Reference
+
+## Header files
+
+- [mosq_broker.h](#file-mosq_brokerh)
+
+## File mosq_broker.h
+
+
+
+
+
+## Structures and Types
+
+| Type | Name |
+| ---: | :--- |
+| struct | [**mosq\_broker\_config**](#struct-mosq_broker_config) <br>_Mosquitto configuration structure._ |
+
+## Functions
+
+| Type | Name |
+| ---: | :--- |
+|  int | [**mosq\_broker\_start**](#function-mosq_broker_start) (struct [**mosq\_broker\_config**](#struct-mosq_broker_config) \*config) <br>_Start mosquitto broker._ |
+
+
+## Structures and Types Documentation
+
+### struct `mosq_broker_config`
+
+_Mosquitto configuration structure._
+
+ESP port of mosquittto supports only the options in this configuration structure.
+
+Variables:
+
+-  char \* host  <br>Address on which the broker is listening for connections
+
+-  int port  <br>Port number of the broker to listen to
+
+
+## Functions Documentation
+
+### function `mosq_broker_start`
+
+_Start mosquitto broker._
+```c
+int mosq_broker_start (
+    struct mosq_broker_config *config
+)
+```
+
+
+This API runs the broker in the calling thread and blocks until the mosquitto exits.
+
+
+
+**Parameters:**
+
+
+* `config` Mosquitto configuration structure
+
+
+**Returns:**
+
+int Exit code (0 on success)

components/mosquitto/examples/broker/main/broker.c

@@ -85,5 +85,5 @@ void app_main(void)
     mqtt_app_start(&config);
 #endif
     // broker continues to run in this task
-    run_broker(&config);
+    mosq_broker_start(&config);
 }

components/mosquitto/generate_api_docs.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+doxygen Doxyfile
+
+esp-doxybook -i doxygen/xml -o ./api.md

components/mosquitto/port/broker.c

@@ -94,7 +94,7 @@ static void listeners__stop(void)
     mosquitto__free(listensock);
 }
 
-int run_broker(struct mosq_broker_config *broker_config)
+int mosq_broker_start(struct mosq_broker_config *broker_config)
 {
 
     struct mosquitto__config config;

components/mosquitto/port/include/mosq_broker.h

@@ -8,9 +8,24 @@
 
 struct mosquitto__config;
 
+/**
+ * @brief Mosquitto configuration structure
+ *
+ * ESP port of mosquittto supports only the options in this configuration
+ * structure.
+ */
 struct mosq_broker_config {
-    char *host;
-    int port;
+    char *host; /*!< Address on which the broker is listening for connections */
+    int port;   /*!< Port number of the broker to listen to */
 };
 
-int run_broker(struct mosq_broker_config *config);
+/**
+ * @brief Start mosquitto broker
+ *
+ * This API runs the broker in the calling thread and blocks until
+ * the mosquitto exits.
+ *
+ * @param config Mosquitto configuration structure
+ * @return int Exit code (0 on success)
+ */
+int mosq_broker_start(struct mosq_broker_config *config);