mirror of
https://github.com/boostorg/mqtt5.git
synced 2025-11-15 15:09:31 +01:00
3abacf7a41
Summary: related to T12804 Reviewers: ivica Reviewed By: ivica Subscribers: miljen, iljazovic Differential Revision: https://repo.mireo.local/D28182
85 lines
5.4 KiB
Plaintext
85 lines
5.4 KiB
Plaintext
[section:configuring_the_client Configuring the Client]
|
|
[nochunk]
|
|
|
|
This section guides you through the steps to properly configure the __Client__ to establish a connection with your chosen MQTT Broker.
|
|
|
|
The __Client__ does *not* expose connect functions (nor asynchronous connect functions).
|
|
Instead, it features a function that will start the Client (see [refmem mqtt_client async_run]).
|
|
All configuration of the __Client__ must be finalised before invoking [refmem mqtt_client async_run].
|
|
Upon calling this function, the __Client__ makes its initial attempt to connect.
|
|
|
|
[section:transport_protocol Choosing a suitable transport protocol]
|
|
|
|
The initial step is selecting an appropriate transport protocol for your MQTT connection.
|
|
|
|
The __MQTT__ protocol relies on an underlying transport protocol that guarantees the orderly and reliable
|
|
transmission of byte streams between the Client and Server in both directions.
|
|
Common transport protocols meeting these criteria include TCP/IP, TLS/SSL for secure transmissions,
|
|
and WebSocket over TCP/IP and TLS/SSL.
|
|
|
|
MQTT Brokers come in various implementations and support different transport protocols.
|
|
Therefore, it is important to familiarise yourself with the protocols your chosen Broker supports.
|
|
Additionally, gather any necessary details such as certificate authority, client certificate, or private keys,
|
|
which might be required for establishing a secure connection.
|
|
|
|
The upcoming examples will demonstrate the configuration and the publishing of a "Hello World!" application message at `QoS` 0,
|
|
using various transport protocols:
|
|
|
|
* [link async_mqtt5.hello_world_over_tcp hello_world_over_tcp.cpp]
|
|
* [link async_mqtt5.hello_world_over_tls hello_world_over_tls.cpp]
|
|
* [link async_mqtt5.hello_world_over_websocket_tcp hello_world_over_websocket_tcp.cpp]
|
|
* [link async_mqtt5.hello_world_over_websocket_tls hello_world_over_websocket_tls.cpp]
|
|
|
|
[endsect] [/transport_protocol]
|
|
|
|
[section:customisation Customising your MQTT connection]
|
|
|
|
The __Client__ offers a variety of functions for customising your MQTT connection settings.
|
|
These functionalities include:
|
|
|
|
* *Specifying a list of Brokers:* You *must* use this function to assign a list of Brokers that the __Client__ will try to connect to (see [refmem mqtt_client brokers]).
|
|
The __Client__ allows for the specification of multiple Brokers for the connections.
|
|
It is important to ensure that *only Brokers belonging to the same cluster are included in this list*.
|
|
Listing Brokers from different clusters may lead to inconsistencies between MQTT Sessions.
|
|
* *Setting connection Credentials:* Set the authentication details (Client Identifier, User Name, Password) (see [refmem mqtt_client credentials]).
|
|
* *Configuring Keep Alive Interval:* Set the maximum allowed interval between two consecutive transmissions from the Client (see [refmem mqtt_client keep_alive]).
|
|
* *Assign a custom user-implemented authenticator:* The custom authentication will be used for __ENHANCED_AUTH__ ([refmem mqtt_client authenticator]).
|
|
* *Defining CONNECT Packet Properties:* Specify properties that will be included in the __CONNECT__ packet sent during connection initiation (see [refmem mqtt_client connect_property] and [refmem mqtt_client connect_properties]).
|
|
|
|
It is important to note that these configurations apply to every Broker listed in [refmem mqtt_client brokers].
|
|
To modify any configuration parameters, you must first stop the __Client__ using [refmem mqtt_client cancel] or [refmem mqtt_client async_disconnect].
|
|
Afterwards, you can re-apply the configurations and restart the __Client__ with [refmem mqtt_client async_run].
|
|
|
|
[endsect] [/customisation]
|
|
|
|
[section:establishing_a_connection Establishing a connection]
|
|
|
|
The __Client__ initiates a connection with the first Broker from the list of Brokers assigned using [refmem mqtt_client brokers].
|
|
A single attempt at connecting involves several steps:
|
|
|
|
# Resolving the Broker's hostname.
|
|
# Creating a TCP connection.
|
|
# Performing the TLS/SSL Handshake /(if applicable)/.
|
|
# Performing the WebSocket Handshake /(if applicable)/.
|
|
# Performing the MQTT handshake. This involves sending the __CONNECT__ packet to the Broker, /(if applicable)/ exchanging __AUTH__ packets (see __ENHANCED_AUTH__), and continuing until the Broker sends the __CONNACK__ packet.
|
|
|
|
The connection is successfully established once the __Client__ receives a __CONNACK__ packet with Reason Code `0x00` (`Success`).
|
|
The attempt fails if any of the following occurs:
|
|
|
|
* Any of the steps from 1 to 5 encounters a failure.
|
|
* The __Client__ does not receive the results of the hostname resolution within `5 seconds`.
|
|
* The __Client__ is unable to complete steps 2 through 5 within `5 seconds`.
|
|
|
|
If this connection attempt is unsuccessful, it proceeds to the next Broker in order, continuing this process until it establishes a connection or exhausts all options without success.
|
|
Upon reaching the end of the list without a successful connection, the __Client__ enters a backoff period before making another round of attempts with the entire list.
|
|
The duration of this backoff period in milliseconds is determined by the formula:
|
|
|
|
2^(min(retry_count, 4)) * 1000 + jitter
|
|
|
|
In this formula, `retry_count` represents the number of complete cycles through the list without a successful connection,
|
|
and `jitter` is a randomly chosen value between `-500ms` to `500ms`, intended to prevent synchronised reconnection attempts in scenarios with multiple clients.
|
|
|
|
[endsect] [/establishing_a_connection]
|
|
|
|
[endsect] [/configuring_the_client]
|