Skip to main content
Version: Mosquitto 2.1

CONNECT

CONNECT PACKAGE

Except clientId there are differences between v.3.1.1 and .v.5.0 except clientId:

clientId:

The clientId identifies each MQTT client that is connecting to an MQTT broker.

v.3.1.1:

mqttProtocol

cleanSession:

cleanSession = 0 In this case the server resumes communication with the client based on the state of the current session (the session is identified by the clientId).

If there is no earlier session, the broker must create a new session.

In case of a connection disconnectiong, the broker must store:

Whether the session exists. Even though a topic has no subscriptions and therefore the session would be without real use.

All subscriptions.

All QoS1 or QoS2 messages that haven't been confirmed by the client yet.

cleanSession = 1

In this case the broker discards any previous sessions and opens a new one.

cleanSession + persistentSession:

To enable a persistent session, the client must set the cleanSession=false.

persistentSession:

All information a client has not been received from the broker since the last connection will be saved on the broker to ensure the client does not miss out on any messages whilst without connection. If the persistent session is active.

Read more about cleanSession and persistentSession here.

lastWill:

The lastWill message is sent by the broker on behalf of the client when a disconnect occurs without a DISCONNECT packet before the actual break-off.

Even though there is no lastWill command part of the packet, we speak about lastWill in general as there are various commands that define and specify how the lastWillMessage will be sent.

lastWillMessage:

The lastWill message is sent by the broker on behalf of the client when a disconnect occurs without a DISCONNECT packet before the actual break-off. So it’s a connection break-off without an earlier announcement.

The lastWill notifies connected clients when this happens.

lastWillTopic:

The MQTT topic that clients subscribed to, who will receive the lastWill message.

lastWillQoS:

If the lastWillQoS is set to 1 or 2, the message will be sent with this QoS level.

lastWillRetain:

Whenever the connection disconnects, the lastWillMessage will be sent within the keepAlive interval (+ half of the interval - see keepAlive) to all subscribers. But also to subscribers that are newly assigned to the topic.

As the client reconnects and publishes a message all subscribers will know that the client is connected again.

keepAlive:

A maximum length of the time interval is defined for each client request to connect with the broker (e.g. 120 seconds). Within the interval, it's ok that the client and broker do not transmit messages. After this interval, the client must send a so-called PING Request packet.

v.5.0:

mqttProtocol

sessionExpiryInterval:

Whenever a session ExpiryInterval is set (e.g. 60) a cleanStart is automatically set to “0”.

With a sessionExpiryInterval active the sessionState will be saved immediately after the keepAlive runs out (e.g. 120 plus half of the keepAlive - that would be 60 seconds in this case).The sessionState is safed for the amount of time set (in this case 60 seconds).

sessionExpiryInterval is solving the problem that you don’t need to send anther CONNECT packet including cleanSession=1 (MQTT v.3.1.1) to discard the session after set it retained.

cleanStart:

cleanStart = 0

In this case the server resumes communication with the client based on the state of the current session (the session is identified by the clientId).

If there is no earlier session, the broker must create a new session.

In case of a connection disconnectiong, the broker must store:

Whether the session exists. Even though a topic has no subscriptions and therefore the session would be without real use.

All subscriptions.

All QoS1 or QoS2 messages that haven't been confirmed by the client yet.

cleanStart = 1

In this case the broker discards any previous sessions and opens a new one.

cleanStart + persistentSession:

To enable a persistent session, the client must set the cleanSession=false.

persistentSession:

All information a client has not been received from the broker since the last connection will be saved on the broker to ensure the client does not miss out on any messages whilst without connection. If the persistent session is active.

Read more about persistentSession here.

username / password:

MQTT can forward and handle username and password within a sent packet. Please be aware that the password is sent as plain text whenever a packet is not encrypted or hashed. Username/password is only for authorization purposes. To keep your connection safe make sure to encrypt your connection.

lastWill:

The lastWill message is sent by the broker on behalf of the client when a disconnect occurs without a DISCONNECT packet before the actual break-off.

Even though there is no lastWill command part of the packet, we speak about lastWill in general as there are various commands that define and specify how the lastWillMessage will be sent.

lastWillMessage:

The lastWill message is sent by the broker on behalf of the client when a disconnect occurs without a DISCONNECT packet before the actual break-off. So it’s a connection break-off without an earlier announcement.

The lastWill notifies connected clients when this happens.

lastWillTopic:

The MQTT topic that clients subscribed to, who will receive the lastWill message.

lastWillQoS:

If the lastWillQoS is set to 1 or 2, the message will be sent with this QoS level.

lastWillRetain:

Whenever the connection disconnects, the lastWillMessage will be sent within the keepAlive interval (+ half of the interval - see keepAlive) to all subscribers. But also to subscribers that are newly assigned to the topic.

As the client reconnects and publishes a message all subscribers will know that the client is connected again.

keepAlive:

A maximum length of the time interval is defined for each client request to connect with the broker (e.g. 120 seconds). Within the interval, it's ok that the client and broker do not transmit messages. After this interval, the client must send a so-called PING Request packet.

PINGREQ

mqttProtocol

The broker must respond with a PING Response (PINGRESP).

mqttProtocol

If a participant is not responding (PINGRESP) - called a "half-open connection", keepAlive takes action. Within the specific time interval plus another half of the very same interval, the broker or client must disconnect. When this happens, the broker sends the lastWill and testament message. As a client is online again whilst a half-open connection is still kept on by the broker, the broker simply performs a client take-over.

CONNACK

mqttProtocol

The broker - in return for the CONNECT package - responds by sending a so-called CONNACK packet (Acknowledge connection request) and the CONNACK return code.

If the client sets cleanSession=false (no cleanSession / persistentSession), the broker must set the sessionPresent=true in the CONNACK packet.

If the client sets cleanSession=true, the broker must respond whether a sessionState (data about the session before a disconnect happened) is stored or not. For the case that there has been a sessionState stored the CONNACK replies with 1. If not, it replies with 0.

The return code indicates whether the reply (sessionPresent) is correct or not. Here you can find a list of all exit statuses (return codes).

PUBLISH PACKET

Except clientId there are differences between v.3.1.1 and .v.5.0 except packetId, topicName and QoS:

mqttProtocol

v.3.1.1

packetId:

Identifies a message.

topicName:

The broker will send the message to all subscribers authorized subscribers that subscribed to this specific topicName.

The topic is set using a simple string.

Topics are treated hierarchically. To delimiter, a slash "/" symbolizes a separation, e.g. “/rooms/room1”.

A subscriber must know about the topic name to subscribe to it.

QoS:

The QoS (Quality of Service) defines a certain level of service that enables the publisher to make sure that the certainty and quantity of a subscriber receiving a sent message equal the importance to receive the message at all, plus whether to receive the message only once.

Also, a subscriber can set a QoS, defining the importance to receive every message, and whether to accept one message multiple times or not.

There are three levels available:

QoS0 is the minimum QoS level:

The broker/client is delivering the message only once, without confirmation.

There is no guarantee that the message sent has been sent to the subscriber. The recipient on the other end does not acknowledge the receipt. Neither is the acknowledgment stored.

The QoS0 - level is often referred to be the "fire and forget"-level.

Using the minimum level of quality can make sense, as MQTT requires to be lightweight, bandwidth-saving, and super fast delivery. QoS0 does not require as many resources from the broker.

Level 1 QoS guarantees the delivery of a message to the receiver at least once.

However, "at least once" means that a single message can be transmitted to the receiver more than once. Thus, this QoS level ensures that a message reaches its subscribers, but does not care about how many times that might be the case.

To achieve this behavior a sender stores a message in a queue until it receives an acknowledgment from the receiver. Within a defined time, the sender sends the message again and again.

Remember: Publishers are always message-senders, and the broker is (not only a data receiver but) also a sender when transmitting messages to subscribers.

Nevertheless, the QoS levels are always set by the clients (the publishers as well as the subscribers) and not by the broker. The broker simply supports all 3 levels and caters to each client and topic individually.

Despite the advantage of guaranteed delivery, QoS1 also entails a disadvantage. It demands and occupies more resources on the sender ́s side.

On the other hand, you really should think about the disadvantages, as QoS1 occupies resources.

Whether to use QoS1 or another level is a design choice and depends on your use case.

How the acknowledgment works

A subscriber must send a so-called PUBACK packet (publish acknowledge) to the broker when the broker demands acknowledgment.

If the subscriber does not send a PUBACK, the broker continues to send PUBLISH packets. If the broker sends the PUBLISH packet again, even the second time, it contains a duplicate flag (DUP).

The packetId enables the broker to match the PUBLISH packet and the PUBACK packet. And the packetId is free and reusable again.

mqttProtocol

The publishing client must store all QoS1 messages which were sent to the broker but which were not (yet) acknowledged/confirmed by the broker.

The broker must store:

  • The information that the session still exists.
  • All subscriptions a client subscribed to.
  • The QoS1 messages waiting to be sent to the client.
  • The QoS1 message, will message and will delay the interval that the client received, but without confirmation.

QoS level 2 guarantees each message is received exactly once.

To do as pleased the broker transmits the PUBLISH packet as usual. But the recipient must respond with a PUBREC (Publish received).

mqttProtocol

After that happens, the broker sends another request, the PUBREL (Publish release), to which the recipient must respond again.

mqttProtocol

The publishing client must store all QoS2 messages sent to the broker without confirmation from the broker.

The broker must store:

  • The information that the session still exists.
  • All subscriptions a client subscribed to.
  • The QoS2 messages waiting to be sent to the client.
  • The QoS2 message, will message and will delay the interval that the client received, but without confirmation.

To discard all stored states and answers a so-called PUBCOMP packet (Publish complete) is sent. That's the end of the QoS2 order of events.

mqttProtocol

Until a PUBCOMP is sent, the broker stores a reference of the original PUBLISH packets packetId.

The packet and packetId become reusable again.

v.3.1.:

mqttProtocol

retainFlag:

In many cases, a device can not wait until the next time the publisher provides information sending a message.

A sensor of a car door tells whether the door is open or closed. As the door is used very infrequently, including a retained flag makes sense.

Without a retained flag set (retainFlag=false), you must wait for the next time the door is opened or closed to find out about the status.

With retained messages (retainFlag=true), you immediately find out, because the retained message gives you the last status.

A retained message safes the last known value of the topic.

It's only possible to save up to one retained message, equal to one retained value.

The retainFlag identifies a message to be a retained message. To identify the message the packetId is used.

Payload:

The actual content of a message is the content of a payload. Whether it's a .mp3-file or .mp4-file, a picture, or a video. Up to 256MB. The payload does not encrypt the content. The broker simply delivers what the publisher inserted into the payload.

dupFlag:

A dupFlag indicates the duplicate of a message.

v.5.0:

mqttProtocol

messageExpiryInterval:

With a sessionExpiryInterval active the sessionState will be saved immediately after the keepAlive (set in the CONNECT packet) runs out (e.g. 120 plus half of the keepAlive - that would be 60 seconds in this case).The sessionState is safed for the amount of time set (in this case 60 seconds).

retainFlag:

In many cases, a device can not wait until the next time the publisher provides information sending a message.

A sensor of a car door tells whether the door is open or closed. As the door is used very infrequently, including a retained flag makes sense.

Without a retained flag set (retainFlag=false), you must wait for the next time the door is opened or closed to find out about the status.

With retained messages (retainFlag=true), you immediately find out, because the retained message gives you the last status.

A retained message safes the last known value of the topic.

It's only possible to save up to one retained message, equal to one retained value.

The retainFlag identifies a message to be a retained message. To identify the message the packetId is used.

Payload:

The actual content of a message is the content of a payload. Whether it's a .mp3-file or .mp4-file, a picture, or a video. Up to 256MB. The payload does not encrypt the content. The broker simply delivers what the publisher inserted into the payload.

dupFlag:

A dupFlag indicates the duplicate of a message.

SUBSCRIBE

SUBSCRIBE Packet

mqttProtocol

packetId:

Unique packet identifier.

subscriptions:

Each subscription consists of a topic and a QoS level.

SUBACK Packet

mqttProtocol

packetId:

Unique packet identifier.

The broker sends one return code for each topic/QoS-pair that it receives in the SUBSCRIBE packet.

The return codes can be:

  • 0 - Success-Maximum QoS0
  • 1 - Success-Maximum QoS1
  • 2 - Success-Maximum QoS2
  • 128 - Failure

UNSUBSCRIBE

mqttProtocol

packetId:

Unique packet identifier.

List of topics:

The UNSUBSCRIBE packet also contains the topics you want to unsubscribe from.

After the packet is sent, the broker unsubscribes the client from the topics.