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

# Publishing a message

Let’s see a minimal working example of publishing a message to the `temperature/outside` topic:

    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())

## Payload encoding

MQTT message payloads are transmitted as byte streams.

aiomqtt accepts payloads of types `int`, `float`, `str`, `bytes`, `bytearray`, and `None`. `int` and `float` payloads are automatically converted to `str` (which is then converted to `bytes`). If you want to send a true `int` or `float`, you can use `struct.pack()` to encode it as a `bytes` object. When no payload is specified or when it’s set to `None`, a zero-length payload is sent.

Note

If you want to send non-standard types, you have to implement the encoding yourself. For example, to send a `dict` as JSON, you can use `json.dumps()` (which returns a `str`). On the receiving end, you can then use `json.loads()` to decode the JSON string back into a `dict`.

## Quality of Service (QoS)

MQTT messages can be sent with different levels of reliability. When publishing a message and when subscribing to a topic you can set the `qos` parameter to one of the three Quality of Service levels:

- QoS 0 (“At most once”): The message is sent once, with no guarantee of delivery. This is the fastest and least reliable option. This is the default of aiomqtt.

- QoS 1 (“At least once”): The message is delivered at least once to the receiver, possibly multiple times. The sender stores messages until the receiver acknowledges receipt.

- QoS 2 (“Exactly once”): The message is delivered exactly once to the receiver, guaranteed through a four-part handshake. This is the slowest and most reliable option.

Important

The QoS levels of the publisher and the subscriber are two different things and don’t have to be the same!

The publisher’s QoS level defines the reliability of the communication between the publisher and the broker. The subscriber’s QoS level defines the reliability of the communication between the broker and the subscriber.

## Retained messages

Messages can be published with the `retain` parameter set to `True`. The broker relays these messages to all subscribers as usual but also stores the most recent message for the topic. Each new subscriber receives the last retained message for a topic immediately after they subscribe.

Important

The broker stores only one retained message per topic. If you publish a new retained message on a topic, the previous retained message is overwritten.

Note

To delete a retained message, you can send a message with an empty payload to the topic. However, it’s usually not useful or necessary to delete retained messages, as new retained messages overwrite the previous ones.