MQTT: Integrate esp-mqtt library into idf

added docs and tests for mqtt library, small fixes (removed warnings, option for custom outbox, websocket bug fixed for longer transports). refactored to use common tcp_transport component, support for CMake build system.
Closes #2108

docs/en/api-reference/protocols/index.rst

@@ -9,5 +9,6 @@ Protocols API
    HTTP Client <esp_http_client>
    HTTP Server <http_server>
    ASIO <asio>
+   ESP-MQTT <mqtt>
 
 Example code for this API section is provided in :example:`protocols` directory of ESP-IDF examples.

docs/en/api-reference/protocols/mqtt.rst

@@ -0,0 +1,112 @@
+ESP-MQTT
+========
+
+Overview
+--------
+
+ESP-MQTT is an implementation of MQTT protocol client (MQTT is a lightweight publish/subscribe messaging protocol).
+
+
+Features
+--------
+   * supports MQTT over TCP, SSL with mbedtls, MQTT over Websocket, MQTT over Websocket Secure.
+   * Easy to setup with URI
+   * Multiple instances (Multiple clients in one application)
+   * Support subscribing, publishing, authentication, will messages, keep alive pings and all 3 QoS levels (it should be a fully functional client).
+
+
+Application Example
+-------------------
+
+    * :example:`protocols/mqtt/tcp`: MQTT over tcp, defalut port 1883
+    * :example:`protocols/mqtt/ssl`:  MQTT over tcp, defalut port 8883
+    * :example:`protocols/mqtt/ws`: MQTT over Websocket, defalut port 80
+    * :example:`protocols/mqtt/wss`: MQTT over Websocket Secure, defalut port 443
+
+
+Configuration
+-------------
+URI
+^^^
+
+-  Curently support ``mqtt``, ``mqtts``, ``ws``, ``wss`` schemes
+-  MQTT over TCP samples:
+
+   -  ``mqtt://iot.eclipse.org``: MQTT over TCP, default port 1883:
+   -  ``mqtt://iot.eclipse.org:1884`` MQTT over TCP, port 1884:
+   -  ``mqtt://username:password@iot.eclipse.org:1884`` MQTT over TCP,
+      port 1884, with username and password
+
+-  MQTT over SSL samples:
+
+   -  ``mqtts://iot.eclipse.org``: MQTT over SSL, port 8883
+   -  ``mqtts://iot.eclipse.org:8884``: MQTT over SSL, port 8884
+
+-  MQTT over Websocket samples:
+
+   -  ``ws://iot.eclipse.org:80/ws``
+
+-  MQTT over Websocket Secure samples:
+
+   -  ``wss://iot.eclipse.org:443/ws``
+
+-  Minimal configurations:
+
+.. code:: c
+
+    const esp_mqtt_client_config_t mqtt_cfg = {
+        .uri = "mqtt://iot.eclipse.org",
+        .event_handle = mqtt_event_handler,
+        // .user_context = (void *)your_context
+    };
+
+-  If there are any options related to the URI in
+   ``esp_mqtt_client_config_t``, the option defined by the URI will be
+   overridden. Sample:
+
+.. code:: c
+
+    const esp_mqtt_client_config_t mqtt_cfg = {
+        .uri = "mqtt://iot.eclipse.org:1234",
+        .event_handle = mqtt_event_handler,
+        .port = 4567,
+    };
+    //MQTT client will connect to iot.eclipse.org using port 4567
+
+SSL
+^^^
+
+-  Get certificate from server, example: ``iot.eclipse.org``
+   ``openssl s_client -showcerts -connect iot.eclipse.org:8883 </dev/null 2>/dev/null|openssl x509 -outform PEM >iot_eclipse_org.pem``
+-  Check the sample application: ``examples/mqtt_ssl``
+-  Configuration:
+
+.. code:: cpp
+
+    const esp_mqtt_client_config_t mqtt_cfg = {
+        .uri = "mqtts://iot.eclipse.org:8883",
+        .event_handle = mqtt_event_handler,
+        .cert_pem = (const char *)iot_eclipse_org_pem_start,
+    };
+
+For more options on ``esp_mqtt_client_config_t``, please refer to API reference below
+
+Change settings in ``menuconfig``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+    make menuconfig 
+    -> Component config -> ESP-MQTT Configuration 
+
+
+- :envvar:`CONFIG_MQTT_PROTOCOL_311`: Enables 3.1.1 version of MQTT protocol
+
+- :envvar:`MQTT_TRANSPORT_%TRANSPORT%`: Enables specific MQTT transport layer, such as SSL, WEBSOCKET, WEBSOCKET_SECURE
+
+- :envvar:`MQTT_CUSTOM_OUTBOX`: Disables default implementation of mqtt_outbox, so a specific implementaion can be supplied
+
+
+API Reference
+-------------
+
+.. include:: /_build/inc/mqtt_client.inc