Adds esp_mqtt_cxx component

- Component moved from esp-idf
- Files moved to adjust to esp-protocol structure

.github/workflows/target-test.yml

@@ -179,6 +179,27 @@ jobs:
             ${{ env.TEST_DIR }}/build/config/sdkconfig.json
           if-no-files-found: error
 
+  build_esp_mqtt_cxx:
+      strategy:
+        matrix:
+          idf_ver: ["latest", "release-v5.0"]
+          idf_target: ["esp32"]
+          test: [ { app: example, path: "components/esp_mqtt_cxx/examples" }]
+      runs-on: ubuntu-20.04
+      container: espressif/idf:${{ matrix.idf_ver }}
+      steps:
+        - name: Checkout esp-protocols
+          uses: actions/checkout@v3
+          with:
+            submodules: recursive
+        - name: Build ${{ matrix.test.app }} with IDF-${{ matrix.idf_ver }} for ${{ matrix.idf_target }}
+          shell: bash
+          working-directory: ${{matrix.test.path}}
+          run: |
+            ${IDF_PATH}/install.sh --enable-pytest
+            . ${IDF_PATH}/export.sh
+            python $IDF_PATH/tools/ci/ci_build_apps.py . --target ${{ matrix.idf_target }} -vv --preserve-all --pytest-app
+
   run-target-websocket:
     name: Run Websocket Example Test on target
     needs: build_websocket

components/esp_mqtt_cxx/CMakeLists.txt

@@ -0,0 +1,8 @@
+idf_build_get_property(target IDF_TARGET)
+
+idf_component_register(SRCS "esp_mqtt_cxx.cpp"
+                    INCLUDE_DIRS "include"
+                    REQUIRES mqtt
+                    )
+
+target_compile_options(${COMPONENT_LIB} PRIVATE "-Wno-format")

components/esp_mqtt_cxx/docs/Doxyfile

@@ -0,0 +1,73 @@
+# This is Doxygen configuration file
+#
+# Doxygen provides over 260 configuration statements
+# To make this file easier to follow,
+# it contains only statements that are non-default
+#
+# NOTE:
+# It is recommended not to change defaults unless specifically required
+# Test any changes how they affect generated documentation
+# Make sure that correct warnings are generated to flag issues with documented code
+#
+# For the complete list of configuration statements see:
+# http://doxygen.nl/manual/config.html
+
+
+PROJECT_NAME = "MQTT C++ client"
+
+## The 'INPUT' statement below is used as input by script 'gen-df-input.py'
+## to automatically generate API reference list files heder_file.inc
+## These files are placed in '_inc' directory
+## and used to include in API reference documentation
+
+INPUT = \
+    $(PROJECT_PATH)/include/esp_mqtt.hpp \
+    $(PROJECT_PATH)/include/esp_mqtt_client_config.hpp
+
+## Get warnings for functions that have no documentation for their parameters or return value
+##
+WARN_NO_PARAMDOC = YES
+
+## Enable preprocessing and remove __attribute__(...) expressions from the INPUT files
+##
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             = \
+    $(ENV_DOXYGEN_DEFINES) \
+    __DOXYGEN__=1 \
+    __attribute__(x)= \
+	_Static_assert()= \
+    IDF_DEPRECATED(X)= \
+    IRAM_ATTR= \
+    configSUPPORT_DYNAMIC_ALLOCATION=1 \
+    configSUPPORT_STATIC_ALLOCATION=1 \
+    configQUEUE_REGISTRY_SIZE=1 \
+    configUSE_RECURSIVE_MUTEXES=1 \
+    configTHREAD_LOCAL_STORAGE_DELETE_CALLBACKS=1 \
+    configNUM_THREAD_LOCAL_STORAGE_POINTERS=1 \
+    configUSE_APPLICATION_TASK_TAG=1 \
+    configTASKLIST_INCLUDE_COREID=1 \
+    "ESP_EVENT_DECLARE_BASE(x)=extern esp_event_base_t x"
+
+## Do not complain about not having dot
+##
+HAVE_DOT = NO
+
+## Generate XML that is required for Breathe
+##
+GENERATE_XML    = YES
+XML_OUTPUT      = xml
+
+GENERATE_HTML   = NO
+HAVE_DOT        = NO
+GENERATE_LATEX  = NO
+GENERATE_MAN    = YES
+
+## Skip distracting progress messages
+##
+QUIET = YES
+## Enable Section Tags for conditional documentation
+##
+ENABLED_SECTIONS += \
+    DOC_EXCLUDE_HEADER_SECTION   ## To conditionally remove doc sections from IDF source files without affecting documentation in upstream files.

components/esp_mqtt_cxx/docs/conf_common.py

@@ -0,0 +1,23 @@
+# flake8: noqa
+from esp_docs.conf_docs import *
+
+extensions += [
+    'sphinx_copybutton',
+    # Needed as a trigger for running doxygen
+    'esp_docs.esp_extensions.dummy_build_system',
+    'esp_docs.esp_extensions.run_doxygen',
+]
+
+# link roles config
+github_repo = 'espressif/esp-protocols'
+
+# context used by sphinx_idf_theme
+html_context['github_user'] = 'espressif'
+html_context['github_repo'] = 'esp-docs'
+
+# Extra options required by sphinx_idf_theme
+project_slug = 'esp-idf'  # >=5.0
+versions_url = 'https://github.com/espressif/esp-protocols/docs/docs_versions.js'
+
+idf_targets = ['esp32']
+languages = ['en']

components/esp_mqtt_cxx/docs/doxygen-known-warnings.txt

@@ -0,0 +1,25 @@
+esp_mqtt_client_config.hpp:line: warning: Compound idf::mqtt::BrokerConfiguration is not documented.
+esp_mqtt_client_config.hpp:line: warning: Compound idf::mqtt::ClientCredentials is not documented.
+esp_mqtt_client_config.hpp:line: warning: Compound idf::mqtt::Configuration is not documented.
+esp_mqtt_client_config.hpp:line: warning: Compound idf::mqtt::Connection is not documented.
+esp_mqtt_client_config.hpp:line: warning: Compound idf::mqtt::Event is not documented.
+esp_mqtt_client_config.hpp:line: warning: Compound idf::mqtt::LastWill is not documented.
+esp_mqtt_client_config.hpp:line: warning: Compound idf::mqtt::Session is not documented.
+esp_mqtt_client_config.hpp:line: warning: Compound idf::mqtt::Task is not documented.
+esp_mqtt_client_config.hpp:line: warning: Member address (variable) of struct idf::mqtt::BrokerConfiguration is not documented.
+esp_mqtt_client_config.hpp:line: warning: Member security (variable) of struct idf::mqtt::BrokerConfiguration is not documented.
+esp_mqtt.hpp:line: warning: Member operator()(esp_mqtt_client *client_handler) (function) of struct idf::mqtt::Client::MqttClientDeleter is not documented.
+esp_mqtt_client_config.hpp:line: warning: Member username (variable) of struct idf::mqtt::ClientCredentials is not documented.
+esp_mqtt_client_config.hpp:line: warning: Member authentication (variable) of struct idf::mqtt::ClientCredentials is not documented.
+esp_mqtt_client_config.hpp:line: warning: Member client_id (variable) of struct idf::mqtt::ClientCredentials is not documented.
+esp_mqtt_client_config.hpp:line: warning: Member event (variable) of struct idf::mqtt::Configuration is not documented.
+esp_mqtt_client_config.hpp:line: warning: Member task (variable) of struct idf::mqtt::Configuration is not documented.
+esp_mqtt_client_config.hpp:line: warning: Member session (variable) of struct idf::mqtt::Configuration is not documented.
+esp_mqtt_client_config.hpp:line: warning: Member connection (variable) of struct idf::mqtt::Configuration is not documented.
+esp_mqtt_client_config.hpp:line: warning: Member data (variable) of struct idf::mqtt::DER is not documented.
+esp_mqtt_client_config.hpp:line: warning: Member len (variable) of struct idf::mqtt::DER is not documented.
+esp_mqtt_client_config.hpp:line: warning: Member ds_data (variable) of struct idf::mqtt::DigitalSignatureData is not documented.
+esp_mqtt_client_config.hpp:line: warning: Member data (variable) of struct idf::mqtt::Password is not documented.
+esp_mqtt_client_config.hpp:line: warning: Member data (variable) of struct idf::mqtt::PEM is not documented.
+esp_mqtt_client_config.hpp:line: warning: Member hint_key (variable) of struct idf::mqtt::PSK is not documented.
+esp_mqtt_client_config.hpp:line: warning: Member last_will (variable) of struct idf::mqtt::Session is not documented.

components/esp_mqtt_cxx/docs/en/conf.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+#
+# English Language RTD & Sphinx config file
+#
+# Uses ../conf_common.py for most non-language-specific settings.
+
+# Importing conf_common adds all the non-language-specific
+# parts to this conf module
+
+try:
+    from conf_common import *  # noqa: F403,F401
+except ImportError:
+    import os
+    import sys
+    sys.path.insert(0, os.path.abspath('../'))
+    from conf_common import *  # noqa: F403,F401
+
+# General information about the project.
+project = u'ESP-Protocols'
+copyright = u'2016 - 2023, Espressif Systems (Shanghai) Co., Ltd'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'en'

components/esp_mqtt_cxx/docs/en/index.rst

@@ -0,0 +1,132 @@
+ESP MQTT C++ client
+====================
+
+Overview
+--------
+The ESP MQTT client is a wrapper over the `esp_mqtt` client with the goal of providing a higher level API.
+
+Features
+--------
+   * Supports MQTT version 3.11
+   * Adds a Filter validation class for topic filters
+   * Split the event handlers to member functions
+
+Configuration
+-------------
+
+The current design uses exception as an error handling mechanism, therefore exceptions need to be enabled in menuconfig.
+
+Usage
+-----
+
+User code needs to inherit fromm :cpp:class:`idf::mqtt::Client` and provide overloads for the event handlers.
+
+.. note:: The handler is available to allow user code to interact directly with it in case of need. This member will likely be made private in the future once the class API stabilizes.
+
+
+.. doxygenclass:: idf::mqtt::Client
+    :members:
+    :protected-members:
+
+Event Handling
+--------------
+
+Events are dispatched throug calls to member functions each one dedicated to a type of event.
+
+Application Example
+-------------------
+
+* :example:`tcp <../examples/tcp>`
+* :example:`ssl <../examples/ssl>`
+
+API Reference
+-------------
+
+Header File
+^^^^^^^^^^^
+
+* :project_file:`include/esp_mqtt.hpp`
+
+Structures
+^^^^^^^^^^
+
+.. doxygenstruct:: idf::mqtt::MQTTException
+    :members:
+
+.. doxygenstruct:: idf::mqtt::Message
+    :members:
+
+Classes
+^^^^^^^
+
+
+.. doxygenclass:: idf::mqtt::Filter
+    :members:
+
+Header File
+^^^^^^^^^^^
+
+* :project_file:`include/esp_mqtt_client_config.hpp`
+
+Structures
+^^^^^^^^^^
+
+.. doxygenstruct:: idf::mqtt::Host
+    :members:
+
+.. doxygenstruct:: idf::mqtt::URI
+    :members:
+
+.. doxygenstruct:: idf::mqtt::BrokerAddress
+    :members:
+
+.. doxygenstruct:: idf::mqtt::PEM
+    :members:
+
+.. doxygenstruct:: idf::mqtt::DER
+    :members:
+
+.. doxygenstruct:: idf::mqtt::Insecure
+    :members:
+
+.. doxygenstruct:: idf::mqtt::GlobalCAStore
+    :members:
+
+.. doxygenstruct:: idf::mqtt::PSK
+    :members:
+
+.. doxygenstruct:: idf::mqtt::Password
+    :members:
+
+.. doxygenstruct:: idf::mqtt::ClientCertificate
+    :members:
+
+.. doxygenstruct:: idf::mqtt::SecureElement
+    :members:
+
+.. doxygenstruct:: idf::mqtt::DigitalSignatureData
+    :members:
+
+.. doxygenstruct:: idf::mqtt::BrokerConfiguration
+    :members:
+
+.. doxygenstruct:: idf::mqtt::ClientCredentials
+    :members:
+
+.. doxygenstruct:: idf::mqtt::Event
+    :members:
+
+.. doxygenstruct:: idf::mqtt::LastWill
+    :members:
+
+.. doxygenstruct:: idf::mqtt::Session
+    :members:
+
+.. doxygenstruct:: idf::mqtt::Task
+    :members:
+
+.. doxygenstruct:: idf::mqtt::Connection
+    :members:
+
+.. doxygenstruct:: idf::mqtt::Configuration
+    :members:

components/esp_mqtt_cxx/docs/generate_docs

@@ -0,0 +1,26 @@
+build-docs --target esp32 --language en
+
+cp -rf _build/en/esp32/html .
+rm -rf _build __pycache__
+
+# Modifes some version and target fields of index.html
+echo "<script type="text/javascript">
+window.onload =(function() {
+    var myAnchor = document.getElementById('version-select');
+    var mySpan = document.createElement('input');
+    mySpan.setAttribute('type', 'text');
+    mySpan.setAttribute('maxLength', '10');
+    mySpan.value = 'latest';
+    mySpan.setAttribute('disabled', true);
+    myAnchor.parentNode.replaceChild(mySpan, myAnchor);
+
+    var myAnchor = document.getElementById('target-select');
+    var mySpan = document.createElement('input');
+    mySpan.setAttribute('type', 'text');
+    mySpan.setAttribute('maxLength', '10');
+    mySpan.value = 'all targets';
+    mySpan.setAttribute('disabled', true);
+    myAnchor.parentNode.replaceChild(mySpan, myAnchor);
+
+})();
+</script>" >> html/index.html

components/esp_mqtt_cxx/esp_mqtt_cxx.cpp

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -62,7 +62,7 @@ void config_broker(esp_mqtt_client_config_t &mqtt_client_cfg, BrokerConfiguratio
             std::visit(overloaded{
                 [&mqtt_client_cfg](PEM const & pem)
                 {
-                    mqtt_client_cfg.broker.verification.certificate= pem.data;
+                    mqtt_client_cfg.broker.verification.certificate = pem.data;
                 }, [&mqtt_client_cfg](DER const & der)
                 {
                     mqtt_client_cfg.broker.verification.certificate = der.data;
@@ -278,15 +278,15 @@ const std::string &Filter::get()
     return filter;
 }
 
-[[nodiscard]] bool Filter::match(char const *const first, int size) const noexcept
+[[nodiscard]] bool Filter::match(char *const begin, int size) const noexcept
 {
-    auto it = static_cast<std::string::const_iterator>(first);
+    auto it = static_cast<std::string::const_iterator>(begin);
     return match(it, it + size);
 }
-std::string::const_iterator Filter::advance(std::string::const_iterator first, std::string::const_iterator last) const
+std::string::const_iterator Filter::advance(std::string::const_iterator begin, std::string::const_iterator end) const
 {
     constexpr auto separator = '/';
-    return std::find(first, last, separator);
+    return std::find(begin, end, separator);
 }
 
 }

components/esp_mqtt_cxx/examples/ssl/CMakeLists.txt

@@ -0,0 +1,14 @@
+# The following four lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.16)
+
+# (Not part of the boilerplate) This example uses an extra component for common
+# functions such as Wi-Fi and Ethernet connection.
+# The path to esp_mqtt_cxx is also added.
+set(EXTRA_COMPONENT_DIRS
+    "../../../../common_components/protocol_examples_common" "../../")
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(mqtt_ssl_cxx)
+
+target_add_binary_data(mqtt_ssl_cxx.elf "main/mqtt_eclipseprojects_io.pem" TEXT)

components/esp_mqtt_cxx/examples/ssl/main/Kconfig.projbuild

@@ -2,7 +2,7 @@ menu "Example Configuration"
 
     config BROKER_URI
         string "Broker URL"
-        default "mqtts://mqtt.eclipse.org:8883"
+        default "mqtts://mqtt.eclipseprojects.io:8883"
         help
             URL of the broker to connect to
 

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

@@ -1,3 +1,8 @@
+/*
+ * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
 /* C++ MQTT (over TCP) Example
 
    This example code is in the Public Domain (or CC0 licensed, at your option.)

components/esp_mqtt_cxx/examples/ssl/pytest_mqtt_ssl.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Unlicense OR CC0-1.0
+import pytest
+
+
+@pytest.mark.esp32
+def test_dummy() -> None:
+    pass

components/esp_mqtt_cxx/examples/ssl/sdkconfig.defaults

@@ -0,0 +1,21 @@
+# Enable C++ exceptions and set emergency pool size for exception objects
+CONFIG_COMPILER_CXX_EXCEPTIONS=y
+CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE=1024
+CONFIG_EXAMPLE_CONNECT_ETHERNET=y
+CONFIG_EXAMPLE_CONNECT_WIFI=n
+CONFIG_EXAMPLE_USE_INTERNAL_ETHERNET=y
+CONFIG_EXAMPLE_ETH_PHY_IP101=y
+CONFIG_EXAMPLE_ETH_MDC_GPIO=23
+CONFIG_EXAMPLE_ETH_MDIO_GPIO=18
+CONFIG_EXAMPLE_ETH_PHY_RST_GPIO=5
+CONFIG_EXAMPLE_ETH_PHY_ADDR=1
+CONFIG_EXAMPLE_CONNECT_IPV6=y
+CONFIG_EXAMPLE_CONNECT_ETHERNET=y
+CONFIG_EXAMPLE_CONNECT_WIFI=n
+CONFIG_EXAMPLE_USE_INTERNAL_ETHERNET=y
+CONFIG_EXAMPLE_ETH_PHY_IP101=y
+CONFIG_EXAMPLE_ETH_MDC_GPIO=23
+CONFIG_EXAMPLE_ETH_MDIO_GPIO=18
+CONFIG_EXAMPLE_ETH_PHY_RST_GPIO=5
+CONFIG_EXAMPLE_ETH_PHY_ADDR=1
+CONFIG_EXAMPLE_CONNECT_IPV6=y

components/esp_mqtt_cxx/examples/tcp/CMakeLists.txt

@@ -4,9 +4,9 @@ cmake_minimum_required(VERSION 3.16)
 
 # (Not part of the boilerplate)
 # This example uses an extra component for common functions such as Wi-Fi and Ethernet connection.
-set(EXTRA_COMPONENT_DIRS $ENV{IDF_PATH}/examples/common_components/protocol_examples_common
-                         $ENV{IDF_PATH}/examples/cxx/experimental/experimental_cpp_component
-                         $ENV{IDF_PATH}/examples/cxx/experimental/esp_mqtt_cxx/components)
+# The path to esp_mqtt_cxx is also added.
+set(EXTRA_COMPONENT_DIRS
+    "../../../../common_components/protocol_examples_common" "../../")
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 project(mqtt_tcp_cxx)

components/esp_mqtt_cxx/examples/tcp/main/Kconfig.projbuild

@@ -2,7 +2,7 @@ menu "Example Configuration"
 
     config BROKER_URL
         string "Broker URL"
-        default "mqtt://mqtt.eclipse.org"
+        default "mqtt://mqtt.eclipseprojects.io"
         help
             URL of the broker to connect to
 

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

@@ -1,3 +1,8 @@
+/*
+ * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
 /* C++ MQTT (over TCP) Example
 
    This example code is in the Public Domain (or CC0 licensed, at your option.)

components/esp_mqtt_cxx/examples/tcp/pytest_mqtt_tcp.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Unlicense OR CC0-1.0
+import pytest
+
+
+@pytest.mark.esp32
+def test_dummy() -> None:
+    pass

components/esp_mqtt_cxx/idf_component.yml

@@ -0,0 +1,8 @@
+version: "0.1.0"
+description: esp mqtt cxx
+url: https://github.com/espressif/esp-protocols/tree/master/components/esp_mqtt_cxx
+dependencies:
+  espressif/esp-idf-cxx: "^1.0.0-beta"
+  # Required IDF version
+  idf:
+    version: ">=5.0"

components/esp_mqtt_cxx/include/esp_mqtt.hpp

@@ -1,16 +1,8 @@
-// Copyright 2021 Espressif Systems (Shanghai) CO LTD
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//         http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
+/*
+ * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
 #pragma once
 
 #include <string_view>
@@ -43,6 +35,9 @@ struct MQTTException : ESPException {
  * AtLeastOnce : Guaranteed delivery of messages. Duplicates can occur.
  * ExactlyOnce : Guaranteed delivery of messages exactly once.
  *
+ * @note
+ *  When subscribing to a topic the QoS means the maximum QoS that should be sent to
+ *  client on this topic
  */
 enum class QoS { AtMostOnce = 0, AtLeastOnce = 1, ExactlyOnce = 2 };
 
@@ -75,7 +70,6 @@ using StringMessage = Message<std::string>;
 
 /**
  * @brief Filter for mqtt topic subscription.
- * @throws std::domain_error if the filter is invalid.
  *
  * Topic filter.
  *
@@ -83,25 +77,31 @@ using StringMessage = Message<std::string>;
 class Filter {
 public:
 
+    /**
+     * @brief Constructs the topic filter from the user filter
+     * @throws std::domain_error if the filter is invalid.
+     *
+     * @param user_filter Filter to be used.
+     */
     explicit Filter(std::string user_filter);
 
 
     /**
      * @brief Get the filter string used.
      *
+     * @return Reference to the topic filter.
      */
     const std::string &get();
 
     /**
      * @brief Checks the filter string against a topic name.
      *
-     * @param first Iterator to the beginning of the sequence.
-     * @param last  Iterator to the end of the sequence.
+     * @param topic_begin Iterator to the beginning of the sequence.
+     * @param topic_end Iterator to the end of the sequence.
      *
      * @return true if the topic name match the filter
      */
-    [[nodiscard]] bool match(std::string::const_iterator first,
-                             std::string::const_iterator last) const noexcept;
+    [[nodiscard]] bool match(std::string::const_iterator topic_begin, std::string::const_iterator topic_end) const noexcept;
 
     /**
      * @brief Checks the filter string against a topic name.
@@ -115,12 +115,12 @@ public:
     /**
      * @brief Checks the filter string against a topic name.
      *
-     * @param first Char array with topic name.
-     * @param last  Size of given topic name.
+     * @param begin Char array with topic name.
+     * @param size  Size of given topic name.
      *
      * @return true if the topic name match the filter
      */
-    [[nodiscard]] bool match(const char *const begin, int size) const noexcept;
+    [[nodiscard]] bool match(char *begin, int size) const noexcept;
 
 
 private:
@@ -149,31 +149,44 @@ enum class MessageID : int {};
  */
 class Client {
 public:
+    /**
+     * @brief Constructor of the client
+     *
+     * @param broker Configuration for broker connection
+     * @param credentials client credentials to be presented to the broker
+     * @param config Mqtt client configuration
+     */
+    Client(const BrokerConfiguration &broker, const ClientCredentials &credentials, const Configuration &config);
 
-    Client(const BrokerConfiguration &broker,const  ClientCredentials &credentials,const  Configuration &config);
-
+    /**
+     * @brief Constructs Client using the same configuration used for
+     * `esp_mqtt_client`
+     * @param config config struct to `esp_mqtt_client`
+     */
     Client(const esp_mqtt_client_config_t &config);
 
     /**
      * @brief Subscribe to topic
      *
-     * @param filter
+     * @param topic_filter MQTT topic filter
      * @param qos QoS subscription, defaulted as QoS::AtLeastOnce
      *
      * @return Optional MessageID. In case of failure std::nullopt is returned.
      */
-    std::optional<MessageID> subscribe(const std::string &filter, QoS qos = QoS::AtLeastOnce);
+    std::optional<MessageID> subscribe(const std::string &topic_filter, QoS qos = QoS::AtLeastOnce);
 
     /**
      * @brief publish message to topic
      *
      * @tparam Container Type for data container. Must be a contiguous memory.
      * @param topic Topic name
-     * @param message Message struct containing data, qos and retain configuration.
+     * @param message Message struct containing data, qos and retain
+     * configuration.
      *
      * @return Optional MessageID. In case of failure std::nullopt is returned.
      */
-    template <class Container> std::optional<MessageID> publish(const std::string &topic, const Message<Container>& message)
+    template <class Container>
+    std::optional<MessageID> publish(const std::string &topic, const Message<Container> &message)
     {
         return publish(topic, std::begin(message.data), std::end(message.data), message.qos, message.retain);
     }
@@ -184,7 +197,8 @@ public:
      * @tparam InputIt Input data iterator type.
      * @param topic Topic name
      * @param first, last Iterator pair of data to publish
-     * @param message Message struct containing data, qos and retain configuration.
+     * @param qos Set qos message
+     * @param retain Set if message should be retained
      *
      * @return Optional MessageID. In case of failure std::nullopt is returned.
      */
@@ -203,6 +217,9 @@ public:
     virtual ~Client() = default;
 
 protected:
+    /**
+     * @brief Helper type to be used as custom deleter for std::unique_ptr.
+     */
     struct MqttClientDeleter {
         void operator()(esp_mqtt_client *client_handler)
         {
@@ -210,20 +227,70 @@ protected:
         }
     };
 
+    /**
+     * @brief Type of the handler for the underlying mqtt_client handler.
+     * It uses std::unique_ptr for lifetime management
+     */
     using ClientHandler = std::unique_ptr<esp_mqtt_client, MqttClientDeleter>;
+    /**
+     * @brief esp_mqtt_client handler
+     *
+     */
     ClientHandler handler;
 
+    /**
+    * @brief Called if there is an error event
+    *
+    * @param event mqtt event data
+    */
+    virtual void on_error(const esp_mqtt_event_handle_t event);
+    /**
+    * @brief Called if there is an disconnection event
+    *
+    * @param event mqtt event data
+    */
+    virtual void on_disconnected(const esp_mqtt_event_handle_t event);
+    /**
+    * @brief Called if there is an subscribed event
+    *
+    * @param event mqtt event data
+    */
+    virtual void on_subscribed(const esp_mqtt_event_handle_t event);
+    /**
+    * @brief Called if there is an unsubscribed event
+    *
+    * @param event mqtt event data
+    */
+    virtual void on_unsubscribed(const esp_mqtt_event_handle_t event);
+    /**
+    * @brief Called if there is an published event
+    *
+    * @param event mqtt event data
+    */
+    virtual void on_published(const esp_mqtt_event_handle_t event);
+    /**
+    * @brief Called if there is an before connect event
+    *
+    * @param event mqtt event data
+    */
+    virtual void on_before_connect(const esp_mqtt_event_handle_t event);
+    /**
+    * @brief Called if there is an connected event
+    *
+    * @param event mqtt event data
+    *
+    */
+    virtual void on_connected(const esp_mqtt_event_handle_t event) = 0;
+    /**
+    * @brief Called if there is an data event
+    *
+    * @param event mqtt event data
+    *
+    */
+    virtual void on_data(const esp_mqtt_event_handle_t event) = 0;
 private:
     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);
-    virtual void on_error(const esp_mqtt_event_handle_t event);
-    virtual void on_disconnected(const esp_mqtt_event_handle_t event);
-    virtual void on_subscribed(const esp_mqtt_event_handle_t event);
-    virtual void on_unsubscribed(const esp_mqtt_event_handle_t event);
-    virtual void on_published(const esp_mqtt_event_handle_t event);
-    virtual void on_before_connect(const esp_mqtt_event_handle_t event);
-    virtual void on_connected(const esp_mqtt_event_handle_t event) = 0;
-    virtual void on_data(const esp_mqtt_event_handle_t event) = 0;
 };
 } // namespace idf::mqtt

components/esp_mqtt_cxx/include/esp_mqtt_client_config.hpp

@@ -1,16 +1,8 @@
-// Copyright 2021 Espressif Systems (Shanghai) CO LTD
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//         http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
+/*
+ * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
 #pragma once
 
 #include <cstddef>

components/esp_websocket_client/examples/CMakeLists.txt

@@ -2,7 +2,7 @@
 # in this exact order for cmake to work correctly
 cmake_minimum_required(VERSION 3.5)
 
-set(EXTRA_COMPONENT_DIRS "../..")
+set(EXTRA_COMPONENT_DIRS "..")
 # This example uses an extra component for common functions such as Wi-Fi and Ethernet connection.
 list(APPEND EXTRA_COMPONENT_DIRS "../../../common_components/protocol_examples_common")
 

examples/cxx/experimental/esp_mqtt_cxx/components/esp_mqtt_cxx/CMakeLists.txt

@@ -1,24 +0,0 @@
-idf_build_get_property(target IDF_TARGET)
-
-idf_component_register(SRCS "esp_mqtt_cxx.cpp"
-                    INCLUDE_DIRS "include"
-                    )
-
-if(TEST_BUILD)
-    message(STATUS "Test build")
-    idf_component_get_property(mqtt_dir mqtt COMPONENT_DIR)
-    idf_component_get_property(experimental_cpp_component_dir experimental_cpp_component COMPONENT_DIR)
-    idf_component_get_property(esp_common_dir esp_common COMPONENT_DIR)
-    idf_component_get_property(esp_event_dir esp_event COMPONENT_DIR)
-    target_include_directories(${COMPONENT_LIB} PUBLIC ${mqtt_dir}/esp-mqtt/include
-                                                       ${esp_event_dir}/include
-                                                       ${experimental_cpp_component_dir}/include
-                                                       ${esp_common_dir}/include)
-
-else()
-    idf_component_get_property(mqtt_lib mqtt COMPONENT_LIB)
-    idf_component_get_property(log_lib log COMPONENT_LIB)
-    idf_component_get_property(experimental_cpp_component_lib experimental_cpp_component COMPONENT_LIB)
-    target_link_libraries(${COMPONENT_LIB} PUBLIC ${log_lib} ${mqtt_lib} ${experimental_cpp_component_lib})
-endif()
-target_compile_options(${COMPONENT_LIB} PRIVATE "-Wno-format")

examples/cxx/experimental/esp_mqtt_cxx/ssl/CMakeLists.txt

@@ -1,14 +0,0 @@
-# The following four lines of boilerplate have to be in your project's CMakeLists
-# in this exact order for cmake to work correctly
-cmake_minimum_required(VERSION 3.16)
-
-# (Not part of the boilerplate)
-# This example uses an extra component for common functions such as Wi-Fi and Ethernet connection.
-set(EXTRA_COMPONENT_DIRS $ENV{IDF_PATH}/examples/common_components/protocol_examples_common
-                         $ENV{IDF_PATH}/examples/cxx/experimental/experimental_cpp_component
-                         $ENV{IDF_PATH}/examples/cxx/experimental/esp_mqtt_cxx/components)
-
-include($ENV{IDF_PATH}/tools/cmake/project.cmake)
-project(mqtt_ssl_cxx)
-
-target_add_binary_data(mqtt_ssl_cxx.elf "main/mqtt_eclipseprojects_io.pem" TEXT)

examples/cxx/experimental/esp_mqtt_cxx/tcp/sdkconfig.defaults

@@ -1,3 +0,0 @@
-# Enable C++ exceptions and set emergency pool size for exception objects
-CONFIG_COMPILER_CXX_EXCEPTIONS=y
-CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE=1024