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¶

protocols/mqtt/tcp: MQTT over tcp, default port 1883

protocols/mqtt/ssl: MQTT over tcp, default port 8883

protocols/mqtt/ws: MQTT over Websocket, default port 80

protocols/mqtt/wss: MQTT over Websocket Secure, default 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:

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

CONFIG_MQTT_PROTOCOL_311: Enables 3.1.1 version of MQTT protocol
CONFIG_MQTT_TRANSPORT_SSL, CONFIG_MQTT_TRANSPORT_WEBSOCKET: Enables specific MQTT transport layer, such as SSL, WEBSOCKET, WEBSOCKET_SECURE
CONFIG_MQTT_CUSTOM_OUTBOX: Disables default implementation of mqtt_outbox, so a specific implementaion can be supplied

API Reference¶

Header File¶

mqtt/esp-mqtt/include/mqtt_client.h

Functions¶

esp_mqtt_client_handle_t esp_mqtt_client_init(const esp_mqtt_client_config_t *config)¶

esp_err_t esp_mqtt_client_set_uri(esp_mqtt_client_handle_t client, const char *uri)¶

esp_err_t esp_mqtt_client_start(esp_mqtt_client_handle_t client)¶

esp_err_t esp_mqtt_client_stop(esp_mqtt_client_handle_t client)¶

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

esp_err_t esp_mqtt_client_unsubscribe(esp_mqtt_client_handle_t client, const char *topic)¶

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

esp_err_t esp_mqtt_client_destroy(esp_mqtt_client_handle_t client)¶

esp_err_t esp_mqtt_set_config(esp_mqtt_client_handle_t client, const esp_mqtt_client_config_t *config)¶

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

MQTT_EVENT_BEFORE_CONNECT¶: The event occurs before connecting

enum esp_mqtt_transport_t¶