MQTT
MQTT is a machine-to-machine (M2M)/"Internet of Things" connectivity protocol. It was designed as an extremely lightweight publish/subscribe messaging transport. It is useful for connections with remote locations where a small code footprint is required and/or network bandwidth is at a premium. For example, it has been used in sensors communicating to a broker via satellite link, over occasional dial-up connections with healthcare providers, and in a range of home automation and small device scenarios. It is also ideal for mobile applications because of its small size, low power usage, minimised data packets, and efficient distribution of information to one or many receivers (more...)
Specification[edit]
http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718008
Server[edit]
Implementation notes of building a MQTT 3.1.1 compliant server.
CONNECT/CONNACK[edit]
Create super basic server that supports a client connection.
Create server application using a TCP/IP Socket listening to port 1883. When a connection is requested open the connection and wait for the first packet of data to be sent from the client. A timeout should be enabled to close the connection if no data is received.
Per the specification the first data received over the new connection must be a CONNECT Control Packet. The following is the simplest possible type of connection, using a new session, and no other connection flags, keep alive, or payload data other than a 0 byte client identifier.
On any data received from a client, read and parse the bytes, it should be structured as follows.
CONNECT Control Packet Byte Bits Dec Description -------------------------------- 0 00010000 1^ Control Packet Type 1 00001100 12 Packet Length 2 00000000 0 Protocol Name Length MSB 3 00000100 4 Protocol Name Length LSB 4 01001101 M* Protocol Name 1st Byte 5 01010001 Q* Protocol Name 2nd Byte 6 01010100 T* Protocol Name 3rd Byte 7 01010100 T* Protocol Name 4th Byte 8 00000100 4 Protocol Level 9 00000010 2 Connect Flags 10 00000000 0 Keep Alive MSB 11 00000000 0 Keep Alive LSB 12 00000000 0 Client Id Length MSB 13 00000000 0 Client Id Length LSB ^First 4-bits only *UTF-8 equivalent of decimal value
The first 4-bits of the packet are the Control Packet Type, here it is "0001" (1) for a CONNECT, the following 4-bits are reserved and must be "0000".
The next byte defines the packet length, not including the header, which makes up the first two bytes of the packet. Here it is "00001010" in binary, or (10), which indicates there are 10 more bytes in the packet. The remaining number of bytes received should be checked and equal to this number to insure data was properly received.
The next two bytes indicate the length of the protocol name, in this case (4).
Following that is the Protocol Name as UTF-8 encoded bytes spelling "MQTT".
Next is the Protocol Level which is (4) for MQTT Version 3.1.1.
The next byte consists of six flags specifying in order the use of: Username, Password, Will Retention, Will QoS (as 2-bits) and Clean Session. The 8th and last bit is reserved and must be "0".
The next two bytes specify a keep alive time in seconds, when set to zero this functionality is not used, and this is the end of the variable header.
The last two bytes specify the length of the client identifier and are the beginning and entirety of the payload.
Upon receiving and verifying a well formed CONNECT, the server must respond with a CONNACK Control Packet. If the packet isn't processed correctly the connection must be closed, otherwise a CONNACK can be returned with a refused error message followed by closing teh connection.
The following packet is sent from the server to the client as a CONNACK acknowledging a successful connection without error.
CONNACK Control Packet Byte Bits Dec Description -------------------------------- 0 00100000 2^ Control Packet Type 1 00000010 2 Packet Length 2 00000000 0 Connect Acknowledge Flags 3 00000000 0 Connect Response Code ^First 4-bits only
The first 4-bits of the packet are the Control Packet Type, here it is "0010" (2) for a CONNACK, the following 4-bits are reserved and must be "0000".
The next byte defines the remaining length of the packet "00000010" (2), this will always be the case as there is no payload for this type.
The following byte is for flags, the fist 7-bits are reserved and always "0000000". The last bit indicates Session Presence, since this is a "clean" session, it will be (0).
The last byte is the response code, (0) indicates connection accepted with no errors. A value of (1-5) means it was refused, and values from (6-255) are reserved.
The client and server have now established a active session and information can be sent to and from client and server.
PINGREQ/PINGRESP[edit]
With an active connection, the client can request a ping with PINGREQ, the server then responds with PINGRESP. This is used to periodically check that the connection is functioning, and can be used to avoid keep alive timeouts if there are extended periods between the sending or receiving of any other type of Control Packet.
Packet sent from client to server initiating PINGREQ ping.
PINGREQ Control Packet Byte Bits Dec Description -------------------------------- 0 11000000 12^ Control Packet Type 1 00000000 0 Packet Length ^First 4-bits only
Packet sent back to client from server PINGRESP pong.
PINGRESP Control Packet Byte Bits Dec Description -------------------------------- 0 11010000 13^ Control Packet Type 1 00000000 0 Packet Length ^First 4-bits only
These packets are always two bytes, the first 4-bits being the Control Packet Type (12 or 13) and the next byte (0) indicating no additional bytes in the packet.
PUBLISH[edit]
PUBLISH can be sent from or to the server, more specifically this gives an example of publishing a Topic "test/message" with QoS (0) and no Payload.
PUBLISH Control Packet Byte Bits Dec Description -------------------------------- 0 00110000 3^ Type, DUP, QoS, RETAIN 1 00001110 14 Packet Length 2 00000000 0 Topic Length MSB 3 00001100 12 Topic Length LSB 4 01110100 t^ Topic 1st Byte 5 01100101 e^ Topic 2nd Byte 6 01110011 s^ Topic 3rd Byte 7 01110100 t^ Topic ... 8 00101111 /^ ... 9 01101101 m^ ... 10 01100101 e^ ... 11 01110011 s^ ... 12 01110011 s^ ... 13 01100001 a^ ... 14 01100111 g^ ... 15 01100101 e^ ... ^First 4-bits only *UTF-8 equivalent of decimal value
Note that the first 4-bits are the Control Packet Type "0011" (3), and the remaining 4-bits are now used for a Duplicate Flag, QoS Level (2 bits) and a Retain Flag respectively.
SUBSCRIBE[edit]
SUBSCRIBE packets are sent from the client to the server to enable the receipt of any matching PUBLISH packets. The Filter(s) specify the Topic to match literally or with the use of wildcards. Each Filter additionally defines the maximum QoS level to use.
SUBSCRIBE Control Packet Byte Bits Dec Description -------------------------------- 0 10000010 8^ Control Packet Type 1 00001010 10 Packet Length 2 00000000 0 Packet Identifier MSB 3 00000000 0 Packet Identifier LSB 4 00000000 0 Filter Length MSB 5 00001100 12 Filter Length LSB 6 01110100 t^ Filter 1st Byte 7 01100101 e^ Filter 2nd Byte 8 01110011 s^ Filter 3rd Byte 9 01110100 t^ Filter ... 10 00101111 /^ ... 11 01101101 m^ ... 12 01100101 e^ ... 13 01110011 s^ ... 14 01110011 s^ ... 15 01100001 a^ ... 16 01100111 g^ ... 17 01100101 e^ ... 18 00000000 0 Filter QoS ^First 4-bits only *UTF-8 equivalent of decimal value
Note the first 4-bits specify the SUBSCRIBE Control Packet "1000" (8), and the following 4-bits are reserved and set to "0010". This is followed by the Packet Length.
Next is a series of filter(s) in a repeating sequence consisting of the first 2 bytes as a 16-bit word defining the length then the UTF-8 encoded string and a final byte defining the QoS.