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

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:
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:
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:
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

API Reference

Functions

esp_mqtt_client_handle_t esp_mqtt_client_init(const esp_mqtt_client_config_t *config)

Creates mqtt client handle based on the configuration.

Return
mqtt_client_handle if successfully created, NULL on error
Parameters
  • config: mqtt configuration structure

esp_err_t esp_mqtt_client_set_uri(esp_mqtt_client_handle_t client, const char *uri)

Sets mqtt connection URI. This API is usually used to overrides the URI configured in esp_mqtt_client_init.

Return
ESP_FAIL if URI parse error, ESP_OK on success
Parameters
  • client: mqtt client hanlde
  • uri:

esp_err_t esp_mqtt_client_start(esp_mqtt_client_handle_t client)

Starts mqtt client with already created client handle.

Return
ESP_OK on success ESP_ERR_INVALID_ARG on wrong initialization ESP_FAIL on other error
Parameters
  • client: mqtt client handle

esp_err_t esp_mqtt_client_reconnect(esp_mqtt_client_handle_t client)

This api is typically used to force reconnection upon a specific event.

Return
ESP_OK on success ESP_FAIL if client is in invalid state
Parameters
  • client: mqtt client handle

esp_err_t esp_mqtt_client_stop(esp_mqtt_client_handle_t client)

Stops mqtt client tasks.

Return
ESP_OK on success ESP_FAIL if client is in invalid state
Parameters
  • client: mqtt client handle

int esp_mqtt_client_subscribe(esp_mqtt_client_handle_t client, const char *topic, int qos)

Subscribe the client to defined topic with defined qos.

Notes:

  • Client must be connected to send subscribe message
  • This API is could be executed from a user task or from a mqtt event callback i.e. internal mqtt task (API is protected by internal mutex, so it might block if a longer data receive operation is in progress.

Return
message_id of the subscribe message on success -1 on failure
Parameters
  • client: mqtt client handle
  • topic:
  • qos:

int esp_mqtt_client_unsubscribe(esp_mqtt_client_handle_t client, const char *topic)

Unsubscribe the client from defined topic.

Notes:

  • Client must be connected to send unsubscribe message
  • It is thread safe, please refer to esp_mqtt_client_subscribe for details

Return
message_id of the subscribe message on success -1 on failure
Parameters
  • client: mqtt client handle
  • topic:

int esp_mqtt_client_publish(esp_mqtt_client_handle_t client, const char *topic, const char *data, int len, int qos, int retain)

Client to send a publish message to the broker.

Notes:

  • Client doesn’t have to be connected to send publish message (although it would drop all qos=0 messages, qos>1 messages would be enqueued)
  • It is thread safe, please refer to esp_mqtt_client_subscribe for details

Return
message_id of the subscribe message on success 0 if cannot publish
Parameters
  • client: mqtt client handle
  • topic: topic string
  • data: payload string (set to NULL, sending empty payload message)
  • len: data length, if set to 0, length is calculated from payload string
  • qos: qos of publish message
  • retain: ratain flag

esp_err_t esp_mqtt_client_destroy(esp_mqtt_client_handle_t client)

Destroys the client handle.

Return
ESP_OK
Parameters
  • client: mqtt client handle

esp_err_t esp_mqtt_set_config(esp_mqtt_client_handle_t client, const esp_mqtt_client_config_t *config)

Set configuration structure, typically used when updating the config (i.e. on “before_connect” event.

Return
ESP_ERR_NO_MEM if failed to allocate ESP_OK on success
Parameters
  • client: mqtt client handle
  • config: mqtt configuration structure

Structures

struct esp_mqtt_event_t

MQTT event configuration structure

Public Members

esp_mqtt_event_id_t event_id

MQTT event type

esp_mqtt_client_handle_t client

MQTT client handle for this event

void *user_context

User context passed from MQTT client config

char *data

Data asociated with this event

int data_len

Lenght of the data for this event

int total_data_len

Total length of the data (longer data are supplied with multiple events)

int current_data_offset

Actual offset for the data asociated with this event

char *topic

Topic asociated with this event

int topic_len

Length of the topic for this event asociated with this event

int msg_id

MQTT messaged id of message

int session_present

MQTT session_present flag for connection event

struct esp_mqtt_client_config_t

MQTT client configuration structure

Public Members

mqtt_event_callback_t event_handle

handle for MQTT events

const char *host

MQTT server domain (ipv4 as string)

const char *uri

Complete MQTT broker URI

uint32_t port

MQTT server port

const char *client_id

default client id is ESP32_CHIPID% where CHIPID% are last 3 bytes of MAC address in hex format

const char *username

MQTT username

const char *password

MQTT password

const char *lwt_topic

LWT (Last Will and Testament) message topic (NULL by default)

const char *lwt_msg

LWT message (NULL by default)

int lwt_qos

LWT message qos

int lwt_retain

LWT retained message flag

int lwt_msg_len

LWT message length

int disable_clean_session

mqtt clean session, default clean_session is true

int keepalive

mqtt keepalive, default is 120 seconds

bool disable_auto_reconnect

this mqtt client will reconnect to server (when errors/disconnect). Set disable_auto_reconnect=true to disable

void *user_context

pass user context to this option, then can receive that context in event->user_context

int task_prio

MQTT task priority, default is 5, can be changed in make menuconfig

int task_stack

MQTT task stack size, default is 6144 bytes, can be changed in make menuconfig

int buffer_size

size of MQTT send/receive buffer, default is 1024

const char *cert_pem

Pointer to certificate data in PEM format for server verify (with SSL), default is NULL, not required to verify the server

const char *client_cert_pem

Pointer to certificate data in PEM format 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.

const char *client_key_pem

Pointer to private key data in PEM format 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.

esp_mqtt_transport_t transport

overrides URI transport

int refresh_connection_after_ms

Refresh connection after this value (in milliseconds)

Type Definitions

typedef struct esp_mqtt_client *esp_mqtt_client_handle_t
typedef esp_mqtt_event_t *esp_mqtt_event_handle_t
typedef esp_err_t (*mqtt_event_callback_t)(esp_mqtt_event_handle_t event)

Enumerations

enum esp_mqtt_event_id_t

MQTT event types.

User event handler receives context data in esp_mqtt_event_t structure with

  • user_context - user data from esp_mqtt_client_config_t
  • client - mqtt client handle
  • various other data depending on event type

Values:

MQTT_EVENT_ERROR = 0
MQTT_EVENT_CONNECTED

connected event, additional context: session_present flag

MQTT_EVENT_DISCONNECTED

disconnected event

MQTT_EVENT_SUBSCRIBED

subscribed event, additional context: msg_id

MQTT_EVENT_UNSUBSCRIBED

unsubscribed event

MQTT_EVENT_PUBLISHED

published event, additional context: msg_id

MQTT_EVENT_DATA

data event, additional context:

  • msg_id message id
  • topic pointer to the received topic
  • topic_len length of the topic
  • data pointer to the received data
  • data_len length of the data for this event
  • current_data_offset offset of the current data for this event
  • total_data_len total length of the data received Note: Multiple MQTT_EVENT_DATA could be fired for one message, if it is longer than internal buffer. In that case only first event contains topic pointer and length, other contain data only with current data length and current data offset updating.

MQTT_EVENT_BEFORE_CONNECT

The event occurs before connecting

enum esp_mqtt_transport_t

Values:

MQTT_TRANSPORT_UNKNOWN = 0x0
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