A communication link using MQTT starts with the client sending a CONNECT message to a broker. Only a client can initiate a session and no client may communicate directly with another client. The broker will always respond back to a CONNECT message with a CONNACK response and status code. Once established the connection remains open. The following are the MQTT messages and formats:
- CONNECT format (client to server): A typical CONNECT message will contain the following (only the clientID is required to initiate a session):
|
Field |
Requirement |
Description |
|
clientID |
Required |
Identifies client to the server. Each client has a unique client ID. It can be between 1 and 23 UTF-8 bytes long. |
|
cleanSession |
Optional |
0: Server must resume communications with the client. Client and server must save session state after disconnect. 1: Client and server must discard and the previous session and start a new one. |
|
username |
Optional |
Name used by the server for authentication. |
|
password |
Optional |
0 to 65536 byte binary password prefixed by 2 bytes of length. |
|
lastWillTopic |
Optional |
Topic branch to publish will message. |
|
lastWillQos |
Optional |
2 bits specifying QoS level when publishing will message. |
|
lastWillMessage |
Optional |
Defines the Will message payload. |
|
lastWillRetain |
Optional |
Specifies if the Will is to be retained when published. |
|
keepAlive |
Optional |
Time interval in seconds. The client is responsible for sending a message or a PINGREQ packet before the keepAlive timer expires. The server will disconnect from the network at 1.5x the Keep Alive period. A value of zero (0) will disable the keepAlive mechanism. |
- CONNECT return codes (server to client): The broker will respond to a CONNECT message with a response code. A designer should be aware that not all connections may be approved by a broker. Response codes are as follows:
|
Return code |
Description |
|
0 |
Successful connection |
|
1 |
Connection refused—unacceptable MQTT protocol version |
|
2 |
Connection refused—client identified is the correct UTF-8, but not allowed by the server |
|
3 |
Connection refused—server is unavailable |
|
4 |
Connection refused—bad username or password |
|
5 |
Connection refused—the client is not authorized to connect |
- PUBLISH format (client to server): At this point, a client may publish data to a topic branch. Each message contains a topic:
|
Field |
Requirement |
Description |
|
packetID |
Required |
Uniquely identifies the packet in the variable header. Client library responsibility. Always set to zero(0) for QoS-0. |
|
topicName |
Required |
Topics branch to publish to (such as US/Wisconsin/Milwaukee/temperature). |
|
qos |
Required |
QoS level 0,1, or 2.
|
|
retainFlag |
Required |
Name used by the server for authentication. |
|
payload |
Optional |
Data format agnostic payload. |
|
dupFlag |
Required |
Message is a duplicate and is resent. |
-
SUBSCRIBE format (client to server): The payload of a subscribe packet includes at least one pair of UTF-8 encoded topicIDs and QoS levels. There may be multiple topicIDs subscribed to in this payload to spare the client from multiple broadcasts:
|
Field |
Requirement |
Description |
|
packetID |
Required |
Uniquely identifies the packet in the variable header. Client library responsibility. |
|
topic_1 |
Required |
Subscribed topic branch. |
|
qos_1 |
Required |
QoS level of messages published to topic_1. |
|
topic_2 |
Optional |
Name used by the server for authentication. |
|
qos2 |
Optional |
QoS level of messages published to topic_2. |
Wildcards can be used to subscribe to multiple topics in a single message. For these examples, the topic will be the full path of "{country}/{states}/{cities}/{temperature,humidity}".
-
+ Single level wildcard: Substitutes a single level in a topic string name. For example, US/+/Milwaukee will substitute the state level and replace it with all 50 states, Alaska to Wyoming.
-
* Multi-level wildcard: Replaces multiple levels rather than a single level. It is always the last character in the topic name. For example, US/Wisconsin/# will subscribe to all Wisconsin cities: Milwaukee, Madison, Glendale, Whitefish Bay, Brookfield, and so on.
-
$ Special topics: This is a special statistical mode for MQTT brokers. Clients cannot publish to $ topics. There is no official standard for use at the moment. One model uses $SYS in the following manner: $SYS/broker/clients/connected.
Several other messages are in the MQTT specification. More details on the MQTT programming API can be found in OASIS MQTT Version 3.1.1 Standard, http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.pdf, 2014.