Configuring the Client

This section guides you through the steps to properly configure the mqtt_client to establish a connection with your chosen MQTT Broker.

The mqtt_client does not expose connect functions (nor asynchronous connect functions). Instead, it features a function that will start the Client (see mqtt_client::async_run). All configuration of the mqtt_client must be finalised before invoking mqtt_client::async_run. Upon calling this function, the mqtt_client makes its initial attempt to connect.

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:

Customising your MQTT connection

The mqtt_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 mqtt_client will try to connect to (see mqtt_client::brokers). The mqtt_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 mqtt_client::credentials).
Configuring Keep Alive Interval: Set the maximum allowed interval between two consecutive transmissions from the Client (see mqtt_client::keep_alive).
Assign a custom user-implemented authenticator: The custom authentication will be used for Enhanced Authentication (mqtt_client::authenticator).
Defining CONNECT Packet Properties: Specify properties that will be included in the CONNECT packet sent during connection initiation (see mqtt_client::connect_property and mqtt_client::connect_properties).

It is important to note that these configurations apply to every Broker listed in mqtt_client::brokers. To modify any configuration parameters, you must first stop the mqtt_client using mqtt_client::cancel or mqtt_client::async_disconnect. Afterwards, you can re-apply the configurations and restart the mqtt_client with mqtt_client::async_run.

Establishing a connection

The mqtt_client initiates a connection with the first Broker from the list of Brokers assigned using 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 Authentication), and continuing until the Broker sends the CONNACK packet.

The connection is successfully established once the mqtt_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 mqtt_client does not receive the results of the hostname resolution within 5 seconds.
The mqtt_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 mqtt_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.