new release

components/protocols/include/mqtt.h

@@ -6,63 +6,108 @@
 #include "esp_err.h"
 
 /**
- * @brief Initializes MQTT client and starts background task if enabled in NVS
+ * @file mqtt.h
+ * @brief MQTT configuration and control interface.
+ *
+ * This module provides initialization, configuration,
+ * and runtime access functions for the MQTT client.
+ *
+ * Configuration is persisted in NVS under namespace "mqtt".
+ */
+
+/* -------------------------------------------------------------------------- */
+/*                                Definitions                                 */
+/* -------------------------------------------------------------------------- */
+
+#define MQTT_MAX_SERVER_LEN 64     /**< Max length for MQTT server URI */
+#define MQTT_MAX_USER_LEN 32       /**< Max length for MQTT username */
+#define MQTT_MAX_PASSWORD_LEN 64   /**< Max length for MQTT password */
+#define MQTT_MAX_BASE_TOPIC_LEN 64 /**< Max length for MQTT base topic */
+
+/* -------------------------------------------------------------------------- */
+/*                              Public Functions                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * @brief Initialize MQTT subsystem.
+ *
+ * Loads configuration from NVS and starts background publish task
+ * if MQTT is enabled. Must be called once during system startup.
  */
 void mqtt_init(void);
 
 /**
- * @brief Set MQTT config
- * 
- * @param enabled 
- * @param server NULL value will be skiped
- * @param base_topic NULL value will be skiped
- * @param user  NULL value will be skiped
- * @param password  NULL value will be skiped
- * @param periodicity 0 value will be skiped
- * @return esp_err_t 
+ * @brief Restart the MQTT client safely.
+ *
+ * Stops the current MQTT client (if running) and starts a new one
+ * with the configuration currently stored in NVS.
+ *
+ * Useful when changing Wi-Fi networks, credentials, or broker settings.
+ *
+ * @return ESP_OK on success, or an ESP_ERR_* code otherwise.
  */
-esp_err_t mqtt_set_config(bool enabled, const char* server, const char* base_topic, const char* user, const char* password, uint16_t periodicity);
+esp_err_t mqtt_restart(void);
 
 /**
- * @brief Get MQTT enabled, stored in NVS
- * 
- * @return true 
- * @return false 
+ * @brief Set and persist MQTT configuration parameters in NVS.
+ *
+ * Any NULL parameter will be skipped (the previous value remains stored).
+ *
+ * @param enabled       Whether MQTT should be enabled (true/false).
+ * @param server        Broker URI (e.g. "mqtt://192.168.1.10").
+ * @param base_topic    Base topic prefix for publish/subscribe.
+ * @param user          MQTT username (optional).
+ * @param password      MQTT password (optional).
+ * @param periodicity   Publish interval (in seconds). Must be >0 when enabled.
+ *
+ * @return ESP_OK on success, or an ESP_ERR_* code otherwise.
+ */
+esp_err_t mqtt_set_config(bool enabled,
+                          const char *server,
+                          const char *base_topic,
+                          const char *user,
+                          const char *password,
+                          uint16_t periodicity);
+
+/**
+ * @brief Get whether MQTT is enabled.
+ *
+ * @return true if enabled, false otherwise.
  */
 bool mqtt_get_enabled(void);
 
 /**
- * @brief Get MQTT server, string length 64, stored in NVS
- * 
- * @param value 
+ * @brief Get MQTT broker URI stored in NVS.
+ *
+ * @param[out] value Buffer to receive the URI (min length: MQTT_MAX_SERVER_LEN).
  */
-void mqtt_get_server(char* value);
+void mqtt_get_server(char *value);
 
 /**
- * @brief Get MQTT password, string length 64, stored in NVS
- * 
- * @param value 
+ * @brief Get MQTT base topic stored in NVS.
+ *
+ * @param[out] value Buffer to receive the base topic (min length: MQTT_MAX_BASE_TOPIC_LEN).
  */
-void mqtt_get_password(char* value); 
+void mqtt_get_base_topic(char *value);
 
 /**
- * @brief Get MQTT base topic, string length 32, stored in NVS
- * 
- * @param value 
+ * @brief Get MQTT username stored in NVS.
+ *
+ * @param[out] value Buffer to receive the username (min length: MQTT_MAX_USER_LEN).
  */
-void mqtt_get_base_topic(char* value);
+void mqtt_get_user(char *value);
 
 /**
- * @brief Get MQTT user, string length 32, stored in NVS
- * 
- * @param value 
+ * @brief Get MQTT password stored in NVS.
+ *
+ * @param[out] value Buffer to receive the password (min length: MQTT_MAX_PASSWORD_LEN).
  */
-void mqtt_get_user(char* value); 
+void mqtt_get_password(char *value);
 
 /**
- * @brief Get MQTT periodicity in second, stored in NVS
- * 
- * @return uint16_t 
+ * @brief Get MQTT publish periodicity in seconds.
+ *
+ * @return Publish interval in seconds (default: 30).
  */
 uint16_t mqtt_get_periodicity(void);