fix(mqtt_cxx): Fix to construct in two steps

to avoid issues with receiving initial (on-connect) event before construction

Closes #631

Author: david-cermak

components/esp_mqtt_cxx/esp_mqtt_cxx.cpp

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -163,7 +163,20 @@ Client::Client(esp_mqtt_client_config_t const &config) :  handler(esp_mqtt_clien
         throw MQTTException(ESP_FAIL);
     };
     CHECK_THROW_SPECIFIC(esp_mqtt_client_register_event(handler.get(), MQTT_EVENT_ANY, mqtt_event_handler, this), mqtt::MQTTException);
+}
+
+void Client::start()
+{
+    if (started) {
+        return;
+    }
     CHECK_THROW_SPECIFIC(esp_mqtt_client_start(handler.get()), mqtt::MQTTException);
+    started = true;
+}
+
+bool Client::is_started() const noexcept
+{
+    return started;
 }
 
 void Client::mqtt_event_handler(void *handler_args, esp_event_base_t base, int32_t event_id, void *event_data) noexcept
@@ -247,6 +260,18 @@ void Client::on_data(esp_mqtt_event_handle_t const event)
 {
 }
 
+void Client::dispatch_event_for_test(int32_t event_id, esp_mqtt_event_t *event)
+{
+    if (event == nullptr) {
+        throw MQTTException(ESP_ERR_INVALID_ARG);
+    }
+    event->event_id = static_cast<esp_mqtt_event_id_t>(event_id);
+    auto err = esp_mqtt_dispatch_custom_event(handler.get(), event);
+    if (err != ESP_OK) {
+        throw MQTTException(err);
+    }
+}
+
 std::optional<MessageID> Client::subscribe(std::string const &topic, QoS qos)
 {
     auto res = esp_mqtt_client_subscribe(handler.get(), topic.c_str(),

components/esp_mqtt_cxx/examples/ssl/main/mqtt_ssl_example.cpp

@@ -83,8 +83,9 @@ extern "C" void app_main(void)
     idf::mqtt::Configuration config{};
 
     MyClient client{broker, credentials, config};
+    client.start();
     while (true) {
         constexpr TickType_t xDelay = 500 / portTICK_PERIOD_MS;
-        vTaskDelay( xDelay );
+        vTaskDelay(xDelay);
     }
 }

components/esp_mqtt_cxx/examples/tcp/main/mqtt_tcp_example.cpp

@@ -78,6 +78,7 @@ extern "C" void app_main(void)
     mqtt::Configuration config{};
 
     MyClient client{broker, credentials, config};
+    client.start();
 
     while (true) {
         constexpr TickType_t xDelay = 500 / portTICK_PERIOD_MS;

components/esp_mqtt_cxx/idf_component.yml

@@ -8,7 +8,7 @@ dependencies:
   espressif/esp-idf-cxx: "^1.0.0-beta"
   # Required IDF version
   idf:
-    version: ">=5.0"
+    version: ">=5.0,<6.0"
   espressif/mqtt:
     rules:
     - if: idf_version >=6.0

components/esp_mqtt_cxx/include/esp_mqtt.hpp

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -165,6 +165,19 @@ class Client {
      */
     Client(const esp_mqtt_client_config_t &config);
 
+    /**
+     * @brief Start the underlying esp-mqtt client
+     *
+     * Must be called after the derived class has finished constructing to avoid
+     * events being dispatched to partially constructed objects.
+     */
+    void start();
+
+    /**
+     * @brief Check whether start() has been called
+     */
+    [[nodiscard]] bool is_started() const noexcept;
+
     /**
      * @brief Subscribe to topic
      *
@@ -216,6 +229,14 @@ class Client {
 
     virtual ~Client() = default;
 
+    /**
+    * @brief Test helper to dispatch events without a broker connection
+    *
+    * Intended for unit tests; forwards directly to the internal event handler.
+    */
+    void dispatch_event_for_test(int32_t event_id, esp_mqtt_event_t *event);
+
+
 protected:
     /**
      * @brief Helper type to be used as custom deleter for std::unique_ptr.
@@ -292,5 +313,6 @@ class Client {
     static void mqtt_event_handler(void *handler_args, esp_event_base_t base, int32_t event_id,
                                    void *event_data) noexcept;
     void init(const esp_mqtt_client_config_t &config);
+    bool started{false};
 };
 } // namespace idf::mqtt