MakeConnection(host::Union{IPAddr, String}, port::Int64;
               ping_timeout=UInt64(60),
               keep_alive::Int64=32,
               client_id::String=randstring(8),
               user::User=User("", ""),
               will::Message=Message(false, 0x00, false, "", UInt8[]),
               clean_session::Bool=true)::Tuple

MakeConnection(path::String;
               ping_timeout=UInt64(60),
               keep_alive::Int64=32,
               client_id::String=randstring(8),
               user::User=User("", ""),
               will::Message=Message(false, 0x00, false, "", UInt8[]),
               clean_session::Bool=true)::Tuple

Creates an MQTT client connection to an MQTT broker, handling the construction of both the Client and Connection objects inside the Configuration struct. This function provides flexible ways to specify the connection details either through a TCP connection with host and port, a Unix Domain Socket path.

Arguments

• host::Union{IPAddr, String}: The IP address or hostname of the MQTT broker.
• port::Int64: The port number to connect to.
• path::String: The file system path for Unix Domain Socket connection.
• io::T: An object of subtype AbstractIOConnection.
• ping_timeout::UInt64: The ping timeout in seconds (default: 60).
• keep_alive::Int64: The keep-alive time in seconds (default: 32).
• client_id::String: The client identifier (default: a random string of length 8).
• user::User: The user credentials for the MQTT broker (default: anonymous user).
• will::Message: The last will message to be sent in case of unexpected disconnection (default: an empty will message).
• clean_session::Bool: Indicates whether to start a clean session (default: true).

Returns

• A Configuration struct where client::Client is the MQTT client instance and connection::Connection is the connection information used to connect to the broker.

This function simplifies the process of setting up an MQTT client connection. Depending on the type of connection, you can specify the broker's IP address and port or a Unix Domain Socket path, it infers the Protocol and then constructs the necessary provided or default parameters. Refer to the documentation for Client and Connection object.

Examples

# Example with IP address and port
client, connection = MakeConnection("127.0.0.1", 1883; client_id="mqtt_client_1")

# Example with Unix Domain Socket path
client, connection = MakeConnection("/var/run/mqtt.sock"; user=User("user", "pass"))

connect_async(client::Client, connection::Connection)

Establishes an asynchronous connection to the MQTT broker using the provided Client and Connection objects. This function initializes the client, establishes the connection, and starts the necessary loops for communication.

Arguments

• client::Client: The MQTT client instance.
• connection::Connection: The connection information used to connect to the broker.

Returns

• A Future object that can be used to await the completion of the connection process.

Example

client, connection = MakeConnection("127.0.0.1", 1883; client_id="mqtt_client_1")
future = connect_async(client, connection)
wait(future)

See Also

• connect: The synchronous version of this function.

connect(protocol::UDS)::PipeEndpoint

Establishes a connection to a Unix domain socket at the given path specified in the UDS struct.

connect(protocol::TCP)::TCPSocket

Establishes a TCP connection to the given IP address and port specified in the TCP struct.

connect(client::Client, connection::Connection)

Establishes a synchronous connection to the MQTT broker using the provided Client and Connection objects. This function wraps connect_async and waits for the connection process to complete.

Arguments

• client::Client: The MQTT client instance.
• connection::Connection: The connection information used to connect to the broker.

Returns

• The result of the connection process after it completes.

The connect function is responsible for establishing a connection between an MQTT client and an MQTT broker. It initializes the client's state, sets up the necessary communication channels, and handles the connection handshake according to the MQTT protocol. When called, connect first ensures that the client's state and resources are properly initialized. This includes resetting the client's state, setting up the socket connection, and creating the channels and locks required for communication. The function then starts the asynchronous tasks needed to manage the read, write, and keep-alive loops, which are crucial for maintaining the connection and ensuring that messages are sent and received properly.

Additionally, the connect function handles the specifics of the MQTT protocol handshake. It constructs and sends the CONNECT packet, including details such as the client ID, user credentials, and optional will message. This handshake process ensures that the broker recognizes the client and sets up the session according to the specified parameters. The synchronous connect function blocks until the connection process is complete, providing a straightforward way to establish the connection without needing to manage asynchronous operations directly. This makes it suitable for applications that require a simple, blocking call to connect to the broker and start communicating immediately.

Example

client, connection = MakeConnection("127.0.0.1", 1883; client_id="mqtt_client_1")
result = connect(client, connection)

See Also

• connect_async: The asynchronous version of this function.
• Client
• Connection

disconnect(client::Client)

Disconnects the client from the broker and stops the tasks.

subscribe_async(client::Client, topic::String, on_msg::Function; qos::UInt8=QOS_0)

Subscribe to a topic asynchronously.

Arguments

• client::Client: The MQTT client.
• topic::String: The topic to subscribe to.
• on_msg::Function: The function to call when a message is received on the topic.
• qos::UInt8: The quality of service level to use for the subscription. Default is 0.

Returns

• Future: A future that can be used to wait for the subscription to complete.

Examples

future = subscribe_async(client, "my/topic", on_msg; qos=QOS_2)

subscribe(client::Client, topic::String, on_msg::Function; qos::UInt8=QOS_0)

Subscribe to a topic.

Arguments

• client::Client: The MQTT client.
• topic::String: The topic to subscribe to.
• on_msg::Function: The function to call when a message is received on the topic.
• qos::UInt8: The quality of service level to use for the subscription. Default is 0.

Examples

subscribe(client, "my/topic", on_msg)

unsubscribe_async(client::Client, topics::String...)

Unsubscribes the Client instance from the supplied topic names. Deletes the callback from the client Returns a Future object that contains nothing on success and an exception on failure.

unsubscribe(client::Client, topics::String...)

Unsubscribes the Client instance from the supplied topic names. Waits until the unsubscribe is fully acknowledged. Returns nothing on success and an exception on failure.

publish_async(client::Client, message::Message)

Publishes the message. Returns a Future object that contains nothing on success and an exception on failure.

publish_async(client::Client, topic::String, payload...;
   dup::Bool=false,
   qos::QOS=QOS_0,
   retain::Bool=false)

Pulishes a message with the specified parameters. Returns a Future object that contains nothing on success and an exception on failure.

publish(client::Client, topic::String, payload...; dup::Bool=false, qos::QOS=QOS_0, retain::Bool=false)

Waits until the publish is completely acknowledged. Publishes a message with the specified parameters. Returns nothign on success and throws an exception on failure.