Chapter 2. API Reference
• user_context: custom context that will be passed to the event handler
• task_prio: MQTT task priority, defaults to 5
• task_stack: MQTT task stack size, defaults to 6144 bytes, setting this will override setting from menu-
config
• buffer_size: size of MQTT send/receive buffer, default is 1024 bytes
• username: pointer to the username used for connecting to the broker
• password: pointer to the password used for connecting to the broker
• client_id: pointer to the client id, defaults to ESP32_%CHIPID% where %CHIPID% are the last 3 bytes
of MAC address in hex format
• host: MQTT broker domain (ipv4 as string), setting the uri will override this
• port: MQTT broker port, specifying the port in the uri will override this
• transport: sets the transport protocol, setting the uri will override this
• refresh_connection_after_ms: refresh connection after this value (in milliseconds)
• event_handle: handle for MQTT events as a callback in legacy mode
• event_loop_handle: handle for MQTT event loop library
For more options on esp_mqtt_client_config_t, please refer to API reference below
Change settings in Project Configuration Menu The settings for MQTT can be found using idf.py menu-
config, under Component config -> ESP-MQTT Configuration
The following settings are available:
• 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 imple-
mentaion can be supplied
Events
The following events may be posted by the MQTT client:
• MQTT_EVENT_BEFORE_CONNECT: The client is initialized and about to start connecting to the broker.
• MQTT_EVENT_CONNECTED: The client has successfully established a connection to the broker. The client
is now ready to send and receive data.
• MQTT_EVENT_DISCONNECTED: The client has aborted the connection due to being unable to read or write
data, e.g. because the server is unavailable.
• MQTT_EVENT_SUBSCRIBED: The broker has acknowledged the client’s subscribe request. The event data
will contain the message ID of the subscribe message.
• MQTT_EVENT_UNSUBSCRIBED: The broker has acknowledged the client’s unsubscribe request. The event
data will contain the message ID of the unsubscribe message.
• MQTT_EVENT_PUBLISHED: The broker has acknowledged the client’s publish message. This will only
be posted for Quality of Service level 1 and 2, as level 0 does not use acknowledgements. The event data will
contain the message ID of the publish message.
• MQTT_EVENT_DATA: The client has received a publish message. The event data contains: message ID, name
of the topic it was published to, received data and its length. For data that exceeds the internal buffer multiple
MQTT_EVENT_DATA will be posted and current_data_offset and total_data_len from event data updated to
keep track of the fragmented message.
• MQTT_EVENT_ERROR: The client has encountered an error. esp_mqtt_error_type_t from error_handle in the
event data can be used to further determine the type of the error. The type of error will determine which parts
of the error_handle struct is filled.
API Reference
Header File
• components/mqtt/esp-mqtt/include/mqtt_client.h
Espressif Systems 510
Submit Document Feedback
Release v4.4
To Next Page