Skip to content

Latest commit

 

History

History
178 lines (122 loc) · 8.53 KB

mqtt.rst

File metadata and controls

178 lines (122 loc) · 8.53 KB
Raw

ESP-MQTT

Overview

ESP-MQTT is an implementation of MQTT protocol client. MQTT is a lightweight publish/subscribe messaging protocol.

Features

  • Support MQTT over TCP, SSL with Mbed TLS, MQTT over WebSocket, and MQTT over WebSocket Secure
  • Easy to setup with URI
  • Multiple instances (multiple clients in one application)
  • Support subscribing, publishing, authentication, last will messages, keep alive pings, and all 3 Quality of Service (QoS) levels (it should be a fully functional client)

Application Examples

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 broker.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.

  • Curently support mqtt, mqtts, ws, wss schemes
  • MQTT over TCP samples:
    • mqtt://mqtt.eclipseprojects.io: MQTT over TCP, default port 1883
    • mqtt://mqtt.eclipseprojects.io:1884: MQTT over TCP, port 1884
    • mqtt://username:password@mqtt.eclipseprojects.io:1884: MQTT over TCP, port 1884, with username and password
  • MQTT over SSL samples:
    • mqtts://mqtt.eclipseprojects.io: MQTT over SSL, port 8883
    • mqtts://mqtt.eclipseprojects.io:8884: MQTT over SSL, port 8884
  • MQTT over WebSocket samples:
    • ws://mqtt.eclipseprojects.io:80/mqtt
  • MQTT over WebSocket Secure samples:
    • wss://mqtt.eclipseprojects.io:443/mqtt
  • Minimal configurations:
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 broker.verification struct must be set. The broker certificate may be set in PEM or DER format. To select DER, the equivalent _len field must be set. Otherwise, a null-terminated string in PEM format should be provided to certificate field.

  • Get certificate from server, example: mqtt.eclipseprojects.io openssl s_client -showcerts -connect mqtt.eclipseprojects.io:8883 </dev/null 2>/dev/null|openssl x509 -outform PEM >mqtt_eclipse_org.pem
  • Check the sample application: examples/mqtt_ssl
  • Configuration:
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 :ref:`esp_tls_server_verification`.

Client Credentials

All client related credentials are under the credentials field.

  • username: pointer to the username used for connecting to the broker, can also be set by URI
  • client_id: pointer to the client ID, defaults to ESP32_%CHIPID% where %CHIPID% are the last 3 bytes of MAC address in hex format

Authentication

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

  • authentication.password: use a password by setting
  • authentication.certificate and authentication.key: mutual authentication with TLS, and both can be provided in PEM or DER format
  • authentication.use_secure_element: use secure element available in ESP32-WROOM-32SE
  • authentication.ds_data: use Digital Signature Peripheral available in some Espressif devices

Session

For MQTT session related configurations, section 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 esp_mqtt_client_config_t.session.last_will struct.

  • topic: pointer to the LWT message topic
  • msg: pointer to the LWT message
  • msg_len: length of the LWT message, required if msg is not null-terminated
  • qos: quality of service for the LWT message
  • retain: specifies the retain flag of the LWT message

Change Settings in Project Configuration Menu

The settings for MQTT can be found using idf.py menuconfig, under Component config > ESP-MQTT Configuration.

The following settings are available:

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

.. include-build-file:: inc/mqtt_client.inc