ESP-MQTT - ESP32 - — ESP-IDF Programming Guide latest documentation (original) (raw)

[中文]

Overview

ESP-MQTT is an implementation of MQTT protocol client, which is a lightweight publish/subscribe messaging protocol. Now ESP-MQTT supports MQTT v5.0.

Features

Application Examples

MQTT Message Retransmission

A new MQTT message can be created by calling esp_mqtt_client_publish or its non-blocking counterpart esp_mqtt_client_enqueue.

Messages with QoS 0 are sent only once. QoS 1 and 2 behave differently since the protocol requires additional steps to complete the process.

The ESP-MQTT library opts to always retransmit unacknowledged QoS 1 and 2 publish messages to prevent data loss in faulty connections, even though the MQTT specification requires the re-transmission only on reconnect with Clean Session flag been set to 0 (set disable_clean_session to true for this behavior).

QoS 1 and 2 messages that may need retransmission are always enqueued, but first transmission try occurs immediately if esp_mqtt_client_publish is used. A transmission retry for unacknowledged messages will occur after message_retransmit_timeout. After CONFIG_MQTT_OUTBOX_EXPIRED_TIMEOUT_MS messages will expire and be deleted. If CONFIG_MQTT_REPORT_DELETED_MESSAGES is set, an event will be sent to notify the user.

Configuration

The configuration is made by setting fields in esp_mqtt_client_config_t struct. The configuration struct has the following sub structs to configure different aspects of the client operation.

In the following sections, the most common aspects are detailed.

Broker

Address

Broker address can be set by usage of address struct. The configuration can be made by usage of uri field or the combination of hostname, transport and port. Optionally, path could be set, this field is useful in WebSocket connections.

The uri field is used in the format scheme://hostname:port/path.

const esp_mqtt_client_config_t mqtt_cfg = { .broker.address.uri = "mqtt://mqtt.eclipseprojects.io", }; esp_mqtt_client_handle_t client = esp_mqtt_client_init(&mqtt_cfg); esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID, mqtt_event_handler, client); esp_mqtt_client_start(client);

Note

By default MQTT client uses event loop library to post related MQTT events (connected, subscribed, published, etc.).

Verification

For secure connections with TLS used, and to guarantee Broker's identity, the verification struct must be set. The broker certificate may be set in PEM or DER format. To select DER, the equivalent certificate_len field must be set. Otherwise, a null-terminated string in PEM format should be provided to certificate field.

const esp_mqtt_client_config_t mqtt_cfg = { .broker = { .address.uri = "mqtts://mqtt.eclipseprojects.io:8883", .verification.certificate = (const char *)mqtt_eclipse_org_pem_start, }, };

For details about other fields, please check the API Reference and TLS Server Verification.

Client Credentials

All client related credentials are under the credentials field.

Authentication

It is possible to set authentication parameters through the authentication field. The client supports the following authentication methods:

Session

For MQTT session-related configurations, session fields should be used.

Last Will and Testament

MQTT allows for a last will and testament (LWT) message to notify other clients when a client ungracefully disconnects. This is configured by the following fields in the last_will struct.

Events

The following events may be posted by the MQTT client:

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.

Parameters:

config -- MQTT configuration structure

Returns:

mqtt_client_handle if successfully created, NULL on error

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.

Parameters:

Returns:

ESP_FAIL if URI parse error, ESP_OK on success

esp_err_t esp_mqtt_client_start(esp_mqtt_client_handle_t client)

Starts MQTT client with already created client handle.

Parameters:

client -- MQTT client handle

Returns:

ESP_OK on success ESP_ERR_INVALID_ARG on wrong initialization ESP_FAIL on other error

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.

Parameters:

client -- MQTT client handle

Returns:

ESP_OK on success ESP_ERR_INVALID_ARG on wrong initialization ESP_FAIL if client is in invalid state

esp_err_t esp_mqtt_client_disconnect(esp_mqtt_client_handle_t client)

This api is typically used to force disconnection from the broker.

Parameters:

client -- MQTT client handle

Returns:

ESP_OK on success ESP_ERR_INVALID_ARG on wrong initialization

esp_err_t esp_mqtt_client_stop(esp_mqtt_client_handle_t client)

Stops MQTT client tasks.

Parameters:

client -- MQTT client handle

Returns:

ESP_OK on success ESP_ERR_INVALID_ARG on wrong initialization ESP_FAIL if client is in invalid state

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

Subscribe the client to defined topic with defined qos.

Notes:

Parameters:

Returns:

message_id of the subscribe message on success -1 on failure -2 in case of full outbox.

int esp_mqtt_client_subscribe_multiple(esp_mqtt_client_handle_t client, const esp_mqtt_topic_t *topic_list, int size)

Subscribe the client to a list of defined topics with defined qos.

Notes:

Parameters:

Returns:

message_id of the subscribe message on success -1 on failure -2 in case of full outbox.

int esp_mqtt_client_unsubscribe(esp_mqtt_client_handle_t client, const char *topic)

Unsubscribe the client from defined topic.

Notes:

Parameters:

Returns:

message_id of the subscribe message on success -1 on failure

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:

Parameters:

Returns:

message_id of the publish message (for QoS 0 message_id will always be zero) on success. -1 on failure, -2 in case of full outbox.

int esp_mqtt_client_enqueue(esp_mqtt_client_handle_t client, const char *topic, const char *data, int len, int qos, int retain, bool store)

Enqueue a message to the outbox, to be sent later. Typically used for messages with qos>0, but could be also used for qos=0 messages if store=true.

This API generates and stores the publish message into the internal outbox and the actual sending to the network is performed in the mqtt-task context (in contrast to the esp_mqtt_client_publish() which sends the publish message immediately in the user task's context). Thus, it could be used as a non blocking version of esp_mqtt_client_publish().

Parameters:

Returns:

message_id if queued successfully, -1 on failure, -2 in case of full outbox.

esp_err_t esp_mqtt_client_destroy(esp_mqtt_client_handle_t client)

Destroys the client handle.

Notes:

Parameters:

client -- MQTT client handle

Returns:

ESP_OK ESP_ERR_INVALID_ARG on wrong initialization

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.

Notes:

Parameters:

Returns:

ESP_ERR_NO_MEM if failed to allocate ESP_ERR_INVALID_ARG if conflicts on transport configuration. ESP_OK on success

esp_err_t esp_mqtt_client_register_event(esp_mqtt_client_handle_t client, esp_mqtt_event_id_t event, esp_event_handler_t event_handler, void *event_handler_arg)

Registers MQTT event.

Parameters:

Returns:

ESP_ERR_NO_MEM if failed to allocate ESP_ERR_INVALID_ARG on wrong initialization ESP_OK on success

esp_err_t esp_mqtt_client_unregister_event(esp_mqtt_client_handle_t client, esp_mqtt_event_id_t event, esp_event_handler_t event_handler)

Unregisters mqtt event.

Parameters:

Returns:

ESP_ERR_NO_MEM if failed to allocate ESP_ERR_INVALID_ARG on invalid event ID ESP_OK on success

int esp_mqtt_client_get_outbox_size(esp_mqtt_client_handle_t client)

Get outbox size.

Parameters:

client -- MQTT client handle

Returns:

outbox size 0 on wrong initialization

esp_err_t esp_mqtt_dispatch_custom_event(esp_mqtt_client_handle_t client, esp_mqtt_event_t *event)

Dispatch user event to the mqtt internal event loop.

Parameters:

Returns:

ESP_OK on success ESP_ERR_TIMEOUT if the event couldn't be queued (ref also CONFIG_MQTT_EVENT_QUEUE_SIZE)

Structures

struct esp_mqtt_error_codes

MQTT error code structure to be passed as a contextual information into ERROR event

Important: This structure extends [esp_tls_last_error](esp%5Ftls.html#structesp%5F%5Ftls%5F%5Flast%5F%5Ferror) error structure and is backward compatible with it (so might be down-casted and treated as [esp_tls_last_error](esp%5Ftls.html#structesp%5F%5Ftls%5F%5Flast%5F%5Ferror) error, but recommended to update applications if used this way previously)

Use this structure directly checking error_type first and then appropriate error code depending on the source of the error:

| error_type | related member variables | note | | MQTT_ERROR_TYPE_TCP_TRANSPORT | esp_tls_last_esp_err, esp_tls_stack_err, esp_tls_cert_verify_flags, sock_errno | Error reported from tcp_transport/esp-tls | | MQTT_ERROR_TYPE_CONNECTION_REFUSED | connect_return_code | Internal error reported from MQTT broker on connection |

Public Members

esp_err_t esp_tls_last_esp_err

last esp_err code reported from esp-tls component

int esp_tls_stack_err

tls specific error code reported from underlying tls stack

int esp_tls_cert_verify_flags

tls flags reported from underlying tls stack during certificate verification

esp_mqtt_error_type_t error_type

error type referring to the source of the error

esp_mqtt_connect_return_code_t connect_return_code

connection refused error code reported from MQTT* broker on connection

int esp_transport_sock_errno

errno from the underlying socket

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

char *data

Data associated with this event

int data_len

Length 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 associated with this event

char *topic

Topic associated with this event

int topic_len

Length of the topic for this event associated with this event

int msg_id

MQTT messaged id of message

int session_present

MQTT session_present flag for connection event

esp_mqtt_error_codes_t *error_handle

esp-mqtt error handle including esp-tls errors as well as internal MQTT errors

bool retain

Retained flag of the message associated with this event

int qos

QoS of the messages associated with this event

bool dup

dup flag of the message associated with this event

esp_mqtt_protocol_ver_t protocol_ver

MQTT protocol version used for connection, defaults to value from menuconfig

struct esp_mqtt_client_config_t

MQTT client configuration structure

Public Members

struct esp_mqtt_client_config_t::broker_t broker

Broker address and security verification

struct esp_mqtt_client_config_t::credentials_t credentials

User credentials for broker

struct esp_mqtt_client_config_t::session_t session

MQTT session configuration.

struct esp_mqtt_client_config_t::network_t network

Network configuration

struct esp_mqtt_client_config_t::task_t task

FreeRTOS task configuration.

struct esp_mqtt_client_config_t::buffer_t buffer

Buffer size configuration.

struct esp_mqtt_client_config_t::outbox_config_t outbox

Outbox configuration.

struct broker_t

Broker related configuration

Public Members

struct esp_mqtt_client_config_t::broker_t::address_t address

Broker address configuration

struct esp_mqtt_client_config_t::broker_t::verification_t verification

Security verification of the broker

struct address_t

Broker address

Public Members

const char *uri

Complete MQTT broker URI

const char *hostname

Hostname, to set ipv4 pass it as string)

esp_mqtt_transport_t transport

Selects transport

const char *path

Path in the URI

uint32_t port

MQTT server port

struct verification_t

Broker identity verification

If fields are not set broker's identity isn't verified. it's recommended to set the options in this struct for security reasons.

Public Members

bool use_global_ca_store

Use a global ca_store, look esp-tls documentation for details.

esp_err_t (*crt_bundle_attach)(void *conf)

Pointer to ESP x509 Certificate Bundle attach function for the usage of certificate bundles. Client only attach the bundle, the clean up must be done by the user.

const char *certificate

Certificate data, default is NULL. It's not copied nor freed by the client, user needs to clean up.

size_t certificate_len

Length of the buffer pointed to by certificate.

const struct psk_key_hint *psk_hint_key

Pointer to PSK struct defined in esp_tls.h to enable PSK authentication (as alternative to certificate verification). PSK is enabled only if there are no other ways to verify broker. It's not copied nor freed by the client, user needs to clean up.

bool skip_cert_common_name_check

Skip any validation of server certificate CN field, this reduces the security of TLS and makes the MQTT client susceptible to MITM attacks

const char **alpn_protos

NULL-terminated list of supported application protocols to be used for ALPN.

const char *common_name

Pointer to the string containing server certificate common name. If non-NULL, server certificate CN must match this name, If NULL, server certificate CN must match hostname. This is ignored if skip_cert_common_name_check=true. It's not copied nor freed by the client, user needs to clean up.

struct buffer_t

Client buffer size configuration

Client have two buffers for input and output respectivelly.

Public Members

int size

size of MQTT send/receive buffer

int out_size

size of MQTT output buffer. If not defined, defaults to the size defined by buffer_size

struct credentials_t

Client related credentials for authentication.

Public Members

const char *username

MQTT username

const char *client_id

Set MQTT client identifier. Ignored if set_null_client_id == true If NULL set the default client id. Default client id is ESP32_CHIPID% where CHIPID% are last 3 bytes of MAC address in hex format

bool set_null_client_id

Selects a NULL client id

struct esp_mqtt_client_config_t::credentials_t::authentication_t authentication

Client authentication

struct authentication_t

Client authentication

Fields related to client authentication by broker

For mutual authentication using TLS, user could select certificate and key, secure element or digital signature peripheral if available.

Public Members

const char *password

MQTT password

const char *certificate

Certificate for ssl mutual authentication, not required if mutual authentication is not needed. Must be provided with key. It's not copied nor freed by the client, user needs to clean up.

size_t certificate_len

Length of the buffer pointed to by certificate.

const char *key

Private key for SSL mutual authentication, not required if mutual authentication is not needed. If it is not NULL, also certificate has to be provided. It's not copied nor freed by the client, user needs to clean up.

size_t key_len

Length of the buffer pointed to by key.

const char *key_password

Client key decryption password, not PEM nor DER, if provided key_password_len must be correctly set.

int key_password_len

Length of the password pointed to by key_password

bool use_secure_element

Enable secure element, available in ESP32-ROOM-32SE, for SSL connection

void *ds_data

Carrier of handle for digital signature parameters, digital signature peripheral is available in some Espressif devices. It's not copied nor freed by the client, user needs to clean up.

struct network_t

Network related configuration

Public Members

int reconnect_timeout_ms

Reconnect to the broker after this value in miliseconds if auto reconnect is not disabled (defaults to 10s)

int timeout_ms

Abort network operation if it is not completed after this value, in milliseconds (defaults to 10s).

int refresh_connection_after_ms

Refresh connection after this value (in milliseconds)

bool disable_auto_reconnect

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

esp_transport_handle_t transport

Custom transport handle to use. Warning: The transport should be valid during the client lifetime and is destroyed when esp_mqtt_client_destroy is called.

struct ifreq *if_name

The name of interface for data to go through. Use the default interface without setting

struct outbox_config_t

Client outbox configuration options.

Public Members

uint64_t limit

Size limit for the outbox in bytes.

struct session_t

MQTT Session related configuration

Public Members

struct esp_mqtt_client_config_t::session_t::last_will_t last_will

Last will configuration

bool disable_clean_session

MQTT clean session, default clean_session is true

int keepalive

MQTT keepalive, default is 120 seconds When configuring this value, keep in mind that the client attempts to communicate with the broker at half the interval that is actually set. This conservative approach allows for more attempts before the broker's timeout occurs

bool disable_keepalive

Set disable_keepalive=true to turn off keep-alive mechanism, keepalive is active by default. Note: setting the config value keepalive to 0 doesn't disable keepalive feature, but uses a default keepalive period

esp_mqtt_protocol_ver_t protocol_ver

MQTT protocol version used for connection.

int message_retransmit_timeout

timeout for retransmitting of failed packet

struct last_will_t

Last Will and Testament message configuration.

Public Members

const char *topic

LWT (Last Will and Testament) message topic

const char *msg

LWT message, may be NULL terminated

int msg_len

LWT message length, if msg isn't NULL terminated must have the correct length

int qos

LWT message QoS

int retain

LWT retained message flag

struct task_t

Client task configuration

Public Members

int priority

MQTT task priority

int stack_size

MQTT task stack size

struct topic_t

Topic definition struct

Public Members

const char *filter

Topic filter to subscribe

int qos

Max QoS level of the subscription

Macros

MQTT_ERROR_TYPE_ESP_TLS

MQTT_ERROR_TYPE_TCP_TRANSPORT error type hold all sorts of transport layer errors, including ESP-TLS error, but in the past only the errors from MQTT_ERROR_TYPE_ESP_TLS layer were reported, so the ESP-TLS error type is re-defined here for backward compatibility

esp_mqtt_client_subscribe(client_handle, topic_type, qos_or_size)

Convenience macro to select subscribe function to use.

Notes:

Parameters:

Returns:

message_id of the subscribe message on success -1 on failure -2 in case of full outbox.

Type Definitions

typedef struct esp_mqtt_client *esp_mqtt_client_handle_t

typedef enum esp_mqtt_event_id_t esp_mqtt_event_id_t

MQTT event types.

User event handler receives context data in [esp_mqtt_event_t](#structesp%5F%5Fmqtt%5F%5Fevent%5F%5Ft) structure with

typedef enum esp_mqtt_connect_return_code_t esp_mqtt_connect_return_code_t

MQTT connection error codes propagated via ERROR event

typedef enum esp_mqtt_error_type_t esp_mqtt_error_type_t

MQTT connection error codes propagated via ERROR event

typedef enum esp_mqtt_transport_t esp_mqtt_transport_t

typedef enum esp_mqtt_protocol_ver_t esp_mqtt_protocol_ver_t

MQTT protocol version used for connection

typedef struct esp_mqtt_error_codes esp_mqtt_error_codes_t

MQTT error code structure to be passed as a contextual information into ERROR event

Important: This structure extends [esp_tls_last_error](esp%5Ftls.html#structesp%5F%5Ftls%5F%5Flast%5F%5Ferror) error structure and is backward compatible with it (so might be down-casted and treated as [esp_tls_last_error](esp%5Ftls.html#structesp%5F%5Ftls%5F%5Flast%5F%5Ferror) error, but recommended to update applications if used this way previously)

Use this structure directly checking error_type first and then appropriate error code depending on the source of the error:

| error_type | related member variables | note | | MQTT_ERROR_TYPE_TCP_TRANSPORT | esp_tls_last_esp_err, esp_tls_stack_err, esp_tls_cert_verify_flags, sock_errno | Error reported from tcp_transport/esp-tls | | MQTT_ERROR_TYPE_CONNECTION_REFUSED | connect_return_code | Internal error reported from MQTT broker on connection |

typedef struct esp_mqtt_event_t esp_mqtt_event_t

MQTT event configuration structure

typedef esp_mqtt_event_t *esp_mqtt_event_handle_t

typedef struct esp_mqtt_client_config_t esp_mqtt_client_config_t

MQTT client configuration structure

typedef struct topic_t esp_mqtt_topic_t

Topic definition struct

Enumerations

enum esp_mqtt_event_id_t

MQTT event types.

User event handler receives context data in [esp_mqtt_event_t](#structesp%5F%5Fmqtt%5F%5Fevent%5F%5Ft) structure with

Values:

enumerator MQTT_EVENT_ANY

enumerator MQTT_EVENT_ERROR

on error event, additional context: connection return code, error handle from esp_tls (if supported)

enumerator MQTT_EVENT_CONNECTED

connected event, additional context: session_present flag

enumerator MQTT_EVENT_DISCONNECTED

disconnected event

enumerator MQTT_EVENT_SUBSCRIBED

subscribed event, additional context:

enumerator MQTT_EVENT_UNSUBSCRIBED

unsubscribed event, additional context: msg_id

enumerator MQTT_EVENT_PUBLISHED

published event, additional context: msg_id

enumerator MQTT_EVENT_DATA

data event, additional context:

enumerator MQTT_EVENT_BEFORE_CONNECT

The event occurs before connecting

enumerator MQTT_EVENT_DELETED

Notification on delete of one message from the internal outbox, if the message couldn't have been sent and acknowledged before expiring defined in OUTBOX_EXPIRED_TIMEOUT_MS. (events are not posted upon deletion of successfully acknowledged messages)

enumerator MQTT_USER_EVENT

Custom event used to queue tasks into mqtt event handler All fields from the esp_mqtt_event_t type could be used to pass an additional context data to the handler.

enum esp_mqtt_connect_return_code_t

MQTT connection error codes propagated via ERROR event

Values:

enumerator MQTT_CONNECTION_ACCEPTED

Connection accepted

enumerator MQTT_CONNECTION_REFUSE_PROTOCOL

MQTT connection refused reason: Wrong protocol

enumerator MQTT_CONNECTION_REFUSE_ID_REJECTED

MQTT connection refused reason: ID rejected

enumerator MQTT_CONNECTION_REFUSE_SERVER_UNAVAILABLE

MQTT connection refused reason: Server unavailable

enumerator MQTT_CONNECTION_REFUSE_BAD_USERNAME

MQTT connection refused reason: Wrong user

MQTT connection refused reason: Wrong username or password

enum esp_mqtt_error_type_t

MQTT connection error codes propagated via ERROR event

Values:

enumerator MQTT_ERROR_TYPE_NONE

enumerator MQTT_ERROR_TYPE_TCP_TRANSPORT

enumerator MQTT_ERROR_TYPE_CONNECTION_REFUSED

enumerator MQTT_ERROR_TYPE_SUBSCRIBE_FAILED

enum esp_mqtt_transport_t

Values:

enumerator MQTT_TRANSPORT_UNKNOWN

enumerator MQTT_TRANSPORT_OVER_TCP

MQTT over TCP, using scheme: MQTT

enumerator MQTT_TRANSPORT_OVER_SSL

MQTT over SSL, using scheme: MQTTS

enumerator MQTT_TRANSPORT_OVER_WS

MQTT over Websocket, using scheme:: ws

enumerator MQTT_TRANSPORT_OVER_WSS

MQTT over Websocket Secure, using scheme: wss

enum esp_mqtt_protocol_ver_t

MQTT protocol version used for connection

Values:

enumerator MQTT_PROTOCOL_UNDEFINED

enumerator MQTT_PROTOCOL_V_3_1

enumerator MQTT_PROTOCOL_V_3_1_1

enumerator MQTT_PROTOCOL_V_5

Header File

Functions

esp_err_t esp_mqtt5_client_set_connect_property(esp_mqtt5_client_handle_t client, const esp_mqtt5_connection_property_config_t *connect_property)

Set MQTT5 client connect property configuration.

Parameters:

Returns:

ESP_ERR_NO_MEM if failed to allocate ESP_ERR_INVALID_ARG on wrong initialization ESP_FAIL on fail ESP_OK on success

esp_err_t esp_mqtt5_client_set_publish_property(esp_mqtt5_client_handle_t client, const esp_mqtt5_publish_property_config_t *property)

Set MQTT5 client publish property configuration.

This API will not store the publish property, it is one-time configuration. Before call esp_mqtt_client_publish to publish data, call this API to set publish property if have

Parameters:

Returns:

ESP_ERR_INVALID_ARG on wrong initialization ESP_FAIL on fail ESP_OK on success

esp_err_t esp_mqtt5_client_set_subscribe_property(esp_mqtt5_client_handle_t client, const esp_mqtt5_subscribe_property_config_t *property)

Set MQTT5 client subscribe property configuration.

This API will not store the subscribe property, it is one-time configuration. Before call esp_mqtt_client_subscribe to subscribe topic, call this API to set subscribe property if have

Parameters:

Returns:

ESP_ERR_INVALID_ARG on wrong initialization ESP_FAIL on fail ESP_OK on success

esp_err_t esp_mqtt5_client_set_unsubscribe_property(esp_mqtt5_client_handle_t client, const esp_mqtt5_unsubscribe_property_config_t *property)

Set MQTT5 client unsubscribe property configuration.

This API will not store the unsubscribe property, it is one-time configuration. Before call esp_mqtt_client_unsubscribe to unsubscribe topic, call this API to set unsubscribe property if have

Parameters:

Returns:

ESP_ERR_INVALID_ARG on wrong initialization ESP_FAIL on fail ESP_OK on success

esp_err_t esp_mqtt5_client_set_disconnect_property(esp_mqtt5_client_handle_t client, const esp_mqtt5_disconnect_property_config_t *property)

Set MQTT5 client disconnect property configuration.

This API will not store the disconnect property, it is one-time configuration. Before call esp_mqtt_client_disconnect to disconnect connection, call this API to set disconnect property if have

Parameters:

Returns:

ESP_ERR_NO_MEM if failed to allocate ESP_ERR_INVALID_ARG on wrong initialization ESP_FAIL on fail ESP_OK on success

esp_err_t esp_mqtt5_client_set_user_property(mqtt5_user_property_handle_t *user_property, esp_mqtt5_user_property_item_t item[], uint8_t item_num)

Set MQTT5 client user property configuration.

This API will allocate memory for user_property, please DO NOT forget call esp_mqtt5_client_delete_user_property after you use it. Before publish data, subscribe topic, unsubscribe, etc, call this API to set user property if have

Parameters:

Returns:

ESP_ERR_NO_MEM if failed to allocate ESP_FAIL on fail ESP_OK on success

esp_err_t esp_mqtt5_client_get_user_property(mqtt5_user_property_handle_t user_property, esp_mqtt5_user_property_item_t *item, uint8_t *item_num)

Get MQTT5 client user property.

This API can use with esp_mqtt5_client_get_user_property_count to get list count of user property. And malloc number of count item array memory to store the user property data. Please DO NOT forget the item memory, key and value point in item memory when get user property data successfully.

Parameters:

Returns:

ESP_ERR_NO_MEM if failed to allocate ESP_FAIL on fail ESP_OK on success

uint8_t esp_mqtt5_client_get_user_property_count(mqtt5_user_property_handle_t user_property)

Get MQTT5 client user property list count.

Parameters:

user_property -- user_property handle

Returns:

user property list count

void esp_mqtt5_client_delete_user_property(mqtt5_user_property_handle_t user_property)

Free the user property list.

This API will free the memory in user property list and free user_property itself

Parameters:

user_property -- user_property handle

Structures

struct esp_mqtt5_connection_property_config_t

MQTT5 protocol connect properties and will properties configuration, more details refer to MQTT5 protocol document section 3.1.2.11 and 3.3.2.3

Public Members

uint32_t session_expiry_interval

The interval time of session expiry

uint32_t maximum_packet_size

The maximum packet size that we can receive

uint16_t receive_maximum

The maximum pakcket count that we process concurrently

uint16_t topic_alias_maximum

The maximum topic alias that we support

bool request_resp_info

This value to request Server to return Response information

bool request_problem_info

This value to indicate whether the reason string or user properties are sent in case of failures

mqtt5_user_property_handle_t user_property

The handle for user property, call function esp_mqtt5_client_set_user_property to set it

uint32_t will_delay_interval

The time interval that server delays publishing will message

uint32_t message_expiry_interval

The time interval that message expiry

bool payload_format_indicator

This value is to indicator will message payload format

const char *content_type

This value is to indicator will message content type, use a MIME content type string

const char *response_topic

Topic name for a response message

const char *correlation_data

Binary data for receiver to match the response message

uint16_t correlation_data_len

The length of correlation data

mqtt5_user_property_handle_t will_user_property

The handle for will message user property, call function esp_mqtt5_client_set_user_property to set it

struct esp_mqtt5_publish_property_config_t

MQTT5 protocol publish properties configuration, more details refer to MQTT5 protocol document section 3.3.2.3

Public Members

bool payload_format_indicator

This value is to indicator publish message payload format

uint32_t message_expiry_interval

The time interval that message expiry

uint16_t topic_alias

An interger value to identify the topic instead of using topic name string

const char *response_topic

Topic name for a response message

const char *correlation_data

Binary data for receiver to match the response message

uint16_t correlation_data_len

The length of correlation data

const char *content_type

This value is to indicator publish message content type, use a MIME content type string

mqtt5_user_property_handle_t user_property

The handle for user property, call function esp_mqtt5_client_set_user_property to set it

struct esp_mqtt5_subscribe_property_config_t

MQTT5 protocol subscribe properties configuration, more details refer to MQTT5 protocol document section 3.8.2.1

Public Members

uint16_t subscribe_id

A variable byte represents the identifier of the subscription

bool no_local_flag

Subscription Option to allow that server publish message that client sent

bool retain_as_published_flag

Subscription Option to keep the retain flag as published option

uint8_t retain_handle

Subscription Option to handle retain option

Whether subscribe is a shared subscription

const char *share_name

The name of shared subscription which is a part of $share/{share_name}/{topic}

mqtt5_user_property_handle_t user_property

The handle for user property, call function esp_mqtt5_client_set_user_property to set it

struct esp_mqtt5_unsubscribe_property_config_t

MQTT5 protocol unsubscribe properties configuration, more details refer to MQTT5 protocol document section 3.10.2.1

Public Members

Whether subscribe is a shared subscription

const char *share_name

The name of shared subscription which is a part of $share/{share_name}/{topic}

mqtt5_user_property_handle_t user_property

The handle for user property, call function esp_mqtt5_client_set_user_property to set it

struct esp_mqtt5_disconnect_property_config_t

MQTT5 protocol disconnect properties configuration, more details refer to MQTT5 protocol document section 3.14.2.2

Public Members

uint32_t session_expiry_interval

The interval time of session expiry

uint8_t disconnect_reason

The reason that connection disconnet, refer to mqtt5_error_reason_code

mqtt5_user_property_handle_t user_property

The handle for user property, call function esp_mqtt5_client_set_user_property to set it

struct esp_mqtt5_event_property_t

MQTT5 protocol for event properties

Public Members

bool payload_format_indicator

Payload format of the message

char *response_topic

Response topic of the message

int response_topic_len

Response topic length of the message

char *correlation_data

Correlation data of the message

uint16_t correlation_data_len

Correlation data length of the message

char *content_type

Content type of the message

int content_type_len

Content type length of the message

uint16_t subscribe_id

Subscription identifier of the message

mqtt5_user_property_handle_t user_property

The handle for user property, call function esp_mqtt5_client_delete_user_property to free the memory

struct esp_mqtt5_user_property_item_t

MQTT5 protocol for user property

Public Members

const char *key

Item key name

const char *value

Item value string

Type Definitions

typedef struct esp_mqtt_client *esp_mqtt5_client_handle_t

typedef struct mqtt5_user_property_list_t *mqtt5_user_property_handle_t

MQTT5 user property handle

Enumerations

enum mqtt5_error_reason_code

MQTT5 protocol error reason code, more details refer to MQTT5 protocol document section 2.4

Values:

enumerator MQTT5_UNSPECIFIED_ERROR

enumerator MQTT5_MALFORMED_PACKET

enumerator MQTT5_PROTOCOL_ERROR

enumerator MQTT5_IMPLEMENT_SPECIFIC_ERROR

enumerator MQTT5_UNSUPPORTED_PROTOCOL_VER

enumerator MQTT5_INVAILD_CLIENT_ID

enumerator MQTT5_INVALID_CLIENT_ID

enumerator MQTT5_BAD_USERNAME_OR_PWD

enumerator MQTT5_NOT_AUTHORIZED

enumerator MQTT5_SERVER_UNAVAILABLE

enumerator MQTT5_SERVER_BUSY

enumerator MQTT5_BANNED

enumerator MQTT5_SERVER_SHUTTING_DOWN

enumerator MQTT5_BAD_AUTH_METHOD

enumerator MQTT5_KEEP_ALIVE_TIMEOUT

enumerator MQTT5_SESSION_TAKEN_OVER

enumerator MQTT5_TOPIC_FILTER_INVAILD

enumerator MQTT5_TOPIC_FILTER_INVALID

enumerator MQTT5_TOPIC_NAME_INVAILD

enumerator MQTT5_TOPIC_NAME_INVALID

enumerator MQTT5_PACKET_IDENTIFIER_IN_USE

enumerator MQTT5_PACKET_IDENTIFIER_NOT_FOUND

enumerator MQTT5_RECEIVE_MAXIMUM_EXCEEDED

enumerator MQTT5_TOPIC_ALIAS_INVAILD

enumerator MQTT5_TOPIC_ALIAS_INVALID

enumerator MQTT5_PACKET_TOO_LARGE

enumerator MQTT5_MESSAGE_RATE_TOO_HIGH

enumerator MQTT5_QUOTA_EXCEEDED

enumerator MQTT5_ADMINISTRATIVE_ACTION

enumerator MQTT5_PAYLOAD_FORMAT_INVAILD

enumerator MQTT5_PAYLOAD_FORMAT_INVALID

enumerator MQTT5_RETAIN_NOT_SUPPORT

enumerator MQTT5_QOS_NOT_SUPPORT

enumerator MQTT5_USE_ANOTHER_SERVER

enumerator MQTT5_SERVER_MOVED

enumerator MQTT5_SHARED_SUBSCR_NOT_SUPPORTED

enumerator MQTT5_CONNECTION_RATE_EXCEEDED

enumerator MQTT5_MAXIMUM_CONNECT_TIME

enumerator MQTT5_SUBSCRIBE_IDENTIFIER_NOT_SUPPORT

enumerator MQTT5_WILDCARD_SUBSCRIBE_NOT_SUPPORT