mqtt5/doc/qbk/02_configuring_the_client.qbk

[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]