Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# Connecting to the broker

To publish messages and subscribe to topics, we first need to connect to a broker. This is a minimal working example that connects to a broker and then publishes a message:

    import asyncio
    import aiomqtt

    async def main():
        async with aiomqtt.Client("test.mosquitto.org") as client:
            await client.publish("temperature/outside", payload=28.4)

    asyncio.run(main())

The connection to the broker is managed by the `Client` context manager. This context manager connects to the broker when we enter the `with` statement and disconnects when we exit it again.

Context managers make it easier to manage resources like network connections or files by ensuring that their teardown logic is always executed – even in case of an exception.

Tip

If your use case does not allow you to use a context manager, you can use the client’s `__aenter__` and `__aexit__` methods to connect and disconnect as a workaround. With this approach you need to ensure yourself that `___aexit___` is also called in case of an exception. Avoid this workaround if you can, it’s a bit tricky to get right.

Note

Examples use the public mosquitto test broker. You can connect to this broker without any credentials. Alternatively, our contribution guide contains an explanation of how to spin up a local mosquitto broker with Docker.

All examples in this documentation are self-contained and runnable as-is.

For a list of all available arguments to the client, see the API reference.

## Sharing the connection

We often want to send and receive messages in multiple different locations in our code. We could create a new client each time, but:

1. This is not very performant, and

2. We’ll use more network bandwidth.

You can share the connection to the broker by passing the `Client` instance to all functions that need it:

    import asyncio
    import aiomqtt

    async def publish_temperature(client):
        await client.publish("temperature/outside", payload=28.4)

    async def publish_humidity(client):
        await client.publish("humidity/inside", payload=0.38)

    async def main():
        async with aiomqtt.Client("test.mosquitto.org") as client:
            await publish_temperature(client)
            await publish_humidity(client)

    asyncio.run(main())

## Persistent sessions

Connections to the MQTT broker can be persistent or non-persistent. Persistent sessions are kept alive when the client goes offline. This means that the broker stores the client’s subscriptions and queues any messages of QoS 1 and 2 that the client misses or has not yet acknowledged. The broker will then retransmit the messages when the client reconnects.

To create a persistent session, set the `clean_session` parameter to `False` when initializing the client. For a non-persistent session, set `clean_session` to `True`.

Note

The amount of messages that can be queued is limited by the broker’s memory. If a client with a persistent session does not come back online for a long time, the broker will eventually run out of memory and start discarding messages.