Merge branch 'feature/mqtt_component' into 'master'

added tuan's mqtt library into idf

See merge request idf/esp-idf!2851

docs/Doxyfile

@@ -92,6 +92,8 @@ INPUT = \
     ##
     ## ESP-TLS
     ../../components/esp-tls/esp_tls.h \
+    ## MQTT
+    ../../components/mqtt/esp-mqtt/include/mqtt_client.h \
     ## mDNS
     ../../components/mdns/include/mdns.h \
     ../../components/esp_http_client/include/esp_http_client.h \

docs/en/COPYRIGHT.rst

@@ -55,6 +55,8 @@ These third party libraries can be included into the application (firmware) prod
 
 * :component:`Asio <asio>`, Copyright (c) 2003-2018 Christopher M. Kohlhoff is licensed under the Boost Software License.
 
+* :component:`ESP-MQTT <mqtt>` MQTT Package (contiki-mqtt) - Copyright (c) 2014, Stephen Robinson, MQTT-ESP - Tuan PM <tuanpm at live dot com> is licensed under Apache License 2.0.
+
 Build Tools
 -----------
 
@@ -155,3 +157,4 @@ Copyright (C) 2011, ChaN, all right reserved.
 .. _Mbed TLS: https://github.com/ARMmbed/mbedtls
 .. _spiffs: https://github.com/pellepl/spiffs
 .. _asio: https://github.com/chriskohlhoff/asio
+.. _mqtt: https://github.com/espressif/esp-mqtt

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

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

@@ -0,0 +1 @@
+.. include:: ../../../en/api-reference/protocols/mqtt.rst