pioduino/esp-idf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update mqtt wifi coexist

Browse Source
This commit is contained in:
Wang Zi Yan
2022-12-20 12:28:38 +08:00
parent 5c8263a08b
commit 996e564f54
4 changed files with 71 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/api-reference/protocols/mqtt.rst
+19 -22
View File
@@ -18,39 +18,36 @@ Features
Application Examples
---------------------
* :example:`protocols/mqtt/tcp`: MQTT over TCP, default port 1883
* :example:`protocols/mqtt/ssl`: MQTT over TLS, default port 8883
* :example:`protocols/mqtt/ssl_ds`: MQTT over TLS using digital signature peripheral for authentication, default port 8883
* :example:`protocols/mqtt/ssl_mutual_auth`: MQTT over TLS using certificates for authentication, default port 8883
* :example:`protocols/mqtt/ssl_psk`: MQTT over TLS using pre-shared keys for authentication, default port 8883
* :example:`protocols/mqtt/ws`: MQTT over WebSocket, default port 80
* :example:`protocols/mqtt/wss`: MQTT over WebSocket Secure, default port 443
* :example:`protocols/mqtt/tcp`: MQTT over TCP, default port 1883
* :example:`protocols/mqtt/ssl`: MQTT over TLS, default port 8883
* :example:`protocols/mqtt/ssl_ds`: MQTT over TLS using digital signature peripheral for authentication, default port 8883
* :example:`protocols/mqtt/ssl_mutual_auth`: MQTT over TLS using certificates for authentication, default port 8883
* :example:`protocols/mqtt/ssl_psk`: MQTT over TLS using pre-shared keys for authentication, default port 8883
* :example:`protocols/mqtt/ws`: MQTT over WebSocket, default port 80
* :example:`protocols/mqtt/wss`: MQTT over WebSocket Secure, default port 443
MQTT message retransmission
MQTT Message Retransmission
---------------------------
A new mqtt message is created by calling :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish()>` or its non blocking
counterpart :cpp:func:`esp_mqtt_client_enqueue <esp_mqtt_client_enqueue()>`.
A new MQTT message is created by calling :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish()>` or its non blocking counterpart :cpp:func:`esp_mqtt_client_enqueue <esp_mqtt_client_enqueue()>`.
Messages with QoS 0 will be sent only once, QoS 1 and 2 have a different behavior since the protocol requires extra steps to complete the process.
Messages with QoS 0 will be sent only once. QoS 1 and 2 have different behaviors since the protocol requires extra steps to complete the process.
The ESP-MQTT library opts to always retransmit unacknowledged QoS 1 and 2 PUBLISH messages to avoid losses in faulty connections, even though the MQTT specification
requires the re-transmission only on reconnect with Clean Session flag been set to 0 (set :cpp:member:`disable_clean_session <esp_mqtt_client_config_t::session_t::disable_clean_session>` to true for this behavior).
The ESP-MQTT library opts to always retransmit unacknowledged QoS 1 and 2 publish messages to avoid losses in faulty connections, even though the MQTT specification requires the re-transmission only on reconnect with Clean Session flag been set to 0 (set :cpp:member:`disable_clean_session <esp_mqtt_client_config_t::session_t::disable_clean_session>` to true for this behavior).
Messages that could need retransmission, QoS 1 and 2, are always enqueued, but first transmission try occurs immediately if :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish>` is used. A transmission retry for unacknowledged messages will occur after :cpp:member:`message_retransmit_timeout <esp_mqtt_client_config_t::session_t::message_retransmit_timeout>`. After :ref:`CONFIG_MQTT_OUTBOX_EXPIRED_TIMEOUT_MS` messages will expire and deleted. If :ref:`CONFIG_MQTT_REPORT_DELETED_MESSAGES` is set an event is sent to notify the user.
QoS 1 and 2 messages that may need retransmission are always enqueued, but first transmission try occurs immediately if :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish>` is used. A transmission retry for unacknowledged messages will occur after :cpp:member:`message_retransmit_timeout <esp_mqtt_client_config_t::session_t::message_retransmit_timeout>`. After :ref:`CONFIG_MQTT_OUTBOX_EXPIRED_TIMEOUT_MS` messages will expire and be deleted. If :ref:`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 :cpp:class:`esp_mqtt_client_config_t` struct. The configuration struct has the following sub structs to configure different aspects of the client operation.
* :cpp:class:`esp_mqtt_client_config_t::broker_t` - Allow to set address and security verification.
* :cpp:class:`esp_mqtt_client_config_t::credentials_t` - Client credentials for authentication.
* :cpp:class:`esp_mqtt_client_config_t::session_t` - Configuration for MQTT session aspects.
* :cpp:class:`esp_mqtt_client_config_t::network_t` - Networking related configuration.
* :cpp:class:`esp_mqtt_client_config_t::task_t` - Allow to configure FreeRTOS task.
* :cpp:class:`esp_mqtt_client_config_t::buffer_t` - Buffer size for input and output.
* :cpp:class:`esp_mqtt_client_config_t::broker_t` - Allow to set address and security verification.
* :cpp:class:`esp_mqtt_client_config_t::credentials_t` - Client credentials for authentication.
* :cpp:class:`esp_mqtt_client_config_t::session_t` - Configuration for MQTT session aspects.
* :cpp:class:`esp_mqtt_client_config_t::network_t` - Networking related configuration.
* :cpp:class:`esp_mqtt_client_config_t::task_t` - Allow to configure FreeRTOS task.
* :cpp:class:`esp_mqtt_client_config_t::buffer_t` - Buffer size for input and output.
In the following sections, the most common aspects are detailed.
@@ -131,7 +128,7 @@ Client Credentials
All client related credentials are under the :cpp:class:`credentials <esp_mqtt_client_config_t::credentials_t>` field.
* :cpp:member:`username <esp_mqtt_client_config_t::credentials_t::username>` pointer to the username used for connecting to the broker, can also be set by URI
* :cpp:member:`username <esp_mqtt_client_config_t::credentials_t::username>`: pointer to the username used for connecting to the broker, can also be set by URI
* :cpp:member:`client_id <esp_mqtt_client_config_t::credentials_t::client_id>`: pointer to the client ID, defaults to ``ESP32_%CHIPID%`` where ``%CHIPID%`` are the last 3 bytes of MAC address in hex format
==============