ESP32 mqtt component
Clone or download
david-cermak Merge branch 'feature/announce_move_to_idf' into 'master'
esp-mqtt announce integration to idf

See merge request idf/esp-mqtt!6
Latest commit 51a5ca0 Oct 10, 2018

Twitter Follow GitHub contributors

ESP32 MQTT Library


  • Based on:
  • Support 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).

How to use

From IDFv3.2 ESP-MQTT is integrated in ESP-IDF as a submodule. Please do not use separately.

For ESP-IDF versions prior to IDFv3.2, please checkout the ESP-MQTT_FOR_IDF_3.1 tag and follow the instructions below:

Clone this component to ESP-IDF project (as submodule):

git submodule add components/espmqtt

Or run a sample (make sure you have installed the toolchain):

git clone
cd espmqtt/examples/mqtt_tcp
make menuconfig
make flash monitor



  • Curently support mqtt, mqtts, ws, wss schemes
  • MQTT over TCP samples:
    • mqtt:// MQTT over TCP, default port 1883:
    • mqtt:// MQTT over TCP, port 1884:
    • mqtt:// MQTT over TCP, port 1884, with username and password
  • MQTT over SSL samples:
    • mqtts:// MQTT over SSL, port 8883
    • mqtts:// MQTT over SSL, port 8884
  • MQTT over Websocket samples:
    • ws://
  • MQTT over Websocket Secure samples:
    • wss://
  • Minimal configurations:
const esp_mqtt_client_config_t mqtt_cfg = {
    .uri = "mqtt://",
    .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:
const esp_mqtt_client_config_t mqtt_cfg = {
    .uri = "mqtt://",
    .event_handle = mqtt_event_handler,
    .port = 4567,
//MQTT client will connect to using port 4567


  • Get Certification from server, example: openssl s_client -showcerts -connect </dev/null 2>/dev/null|openssl x509 -outform PEM >iot_eclipse_org.pem
  • Check the sample application: examples/mqtt_ssl
  • Configuration:
const esp_mqtt_client_config_t mqtt_cfg = {
    .uri = "mqtts://",
    .event_handle = mqtt_event_handler,
    .cert_pem = (const char *)iot_eclipse_org_pem_start,

More options for esp_mqtt_client_config_t

  • event_handle for MQTT events
  • host: MQTT server domain (ipv4 as string)
  • port: MQTT server port
  • client_id: default client id is ESP32_%CHIPID%
  • username: MQTT username
  • password: MQTT password
  • lwt_topic, lwt_msg, lwt_qos, lwt_retain, lwt_msg_len: are mqtt lwt options, default NULL
  • disable_clean_session: mqtt clean session, default clean_session is true
  • keepalive: (value in seconds) mqtt keepalive, default is 120 seconds
  • disable_auto_reconnect: this mqtt client will reconnect to server (when errors/disconnect). Set disable_auto_reconnect=true to disable
  • user_context pass user context to this option, then can receive that context in event->user_context
  • task_prio, task_stack for MQTT task, default priority is 5, and task_stack = 6144 bytes (or default task stack can be set via make menucofig).
  • buffer_size for MQTT send/receive buffer, default is 1024
  • cert_pem pointer to CERT file for server verify (with SSL), default is NULL, not required to verify the server
  • client_cert_pem pointer to CERT file for SSL mutual authentication, default is NULL, not required if mutual authentication is not needed. If it is not NULL, also client_key_pem has to be provided.
  • client_key_pem pointer to PEM private key file for SSL mutual authentication, default is NULL, not required if mutual authentication is not needed. If it is not NULL, also client_cert_pem has to be provided.
  • transport: override URI transport
    • MQTT_TRANSPORT_OVER_TCP: MQTT over TCP, using scheme: mqtt
    • MQTT_TRANSPORT_OVER_SSL: MQTT over SSL, using scheme: mqtts
    • MQTT_TRANSPORT_OVER_WS: MQTT over Websocket, using scheme: ws
    • MQTT_TRANSPORT_OVER_WSS: MQTT over Websocket Secure, using scheme: wss

Change settings in menuconfig

make menuconfig 
-> Component config -> ESPMQTT Configuration 


Check examples/mqtt_tcp and examples/mqtt_ssl project. In Short:

static esp_err_t mqtt_event_handler(esp_mqtt_event_handle_t event)
    esp_mqtt_client_handle_t client = event->client;
    int msg_id;
    // your_context_t *context = event->context;
    switch (event->event_id) {
            msg_id = esp_mqtt_client_subscribe(client, "/topic/qos0", 0);
            ESP_LOGI(TAG, "sent subscribe successful, msg_id=%d", msg_id);

            msg_id = esp_mqtt_client_subscribe(client, "/topic/qos1", 1);
            ESP_LOGI(TAG, "sent subscribe successful, msg_id=%d", msg_id);

            msg_id = esp_mqtt_client_unsubscribe(client, "/topic/qos1");
            ESP_LOGI(TAG, "sent unsubscribe successful, msg_id=%d", msg_id);

            ESP_LOGI(TAG, "MQTT_EVENT_SUBSCRIBED, msg_id=%d", event->msg_id);
            msg_id = esp_mqtt_client_publish(client, "/topic/qos0", "data", 0, 0, 0);
            ESP_LOGI(TAG, "sent publish successful, msg_id=%d", msg_id);
            ESP_LOGI(TAG, "MQTT_EVENT_UNSUBSCRIBED, msg_id=%d", event->msg_id);
            ESP_LOGI(TAG, "MQTT_EVENT_PUBLISHED, msg_id=%d", event->msg_id);
        case MQTT_EVENT_DATA:
            printf("TOPIC=%.*s\r\n", event->topic_len, event->topic);
            printf("DATA=%.*s\r\n", event->data_len, event->data);
        case MQTT_EVENT_ERROR:
    return ESP_OK;
const esp_mqtt_client_config_t mqtt_cfg = {
    .uri = "mqtt://",
    .event_handle = mqtt_event_handler,
    // .user_context = (void *)your_context

esp_mqtt_client_handle_t client = esp_mqtt_client_init(&mqtt_cfg);