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 8883mqtts://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
API Reference¶
Header File¶
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
-
esp_mqtt_event_id_t
-
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)
-
mqtt_event_callback_t
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 withuser_context
- user data fromesp_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
¶ 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
-