2 releases
0.1.1 | Dec 9, 2018 |
---|---|
0.1.0 | Dec 8, 2018 |
#2 in #byte-length
43 downloads per month
64KB
1.5K
SLoC
RustMqtt
Mqtt encoder and decoder for pure rust.
Notes
- The byte order for
mqtt
packets isBig-Endian
, means all the bytes will be arranged atMSB
->LSB
. - Strings/Text values are
UTF-8
, the format is2-byte
+n-bytes
, where first2-byte
are length of the string and anothern-bytes
is the actual textual data. Max length of text field is65535
bytes.
Control Packets
All the MQtt
control packets consists of 3 parts.
Fixed header
, present in all MQTT Control Packets.Variable header
, present in some MQTT Control Packets.Payload
, present in some MQTT Control Packets.
1. Fixed Header
- First byte in fixed header contains various settings as well as what type of packet this is.
7th 6th 5th 4th
, these4 bits
are the type of packet.3rd 2nd 1st 0th
, these4 bits
arepacket specific
. mostly utilized forpublish
packet type.
- Second on wards bytes contains the actual remaining length of the whole packet including variable header and payload if any.
- The Remaining Length is encoded using a variable length encoding scheme which uses a single byte for values up to 127. Larger values are handled as follows. The least significant seven bits of each byte encode the data, and the most significant bit is used to indicate that there are following bytes in the representation. Thus each byte encodes 128 values and "continuation bit". The maximum number of bytes in the Remaining Length field is four.
-
do encodedByte = X MOD 128 X = X DIV 128 // if there are more data to encode, set the top bit of this byte if ( X > 0 ) encodedByte = encodedByte OR 128 endif 'output' encodedByte while ( X > 0 )
2. Variable Header
- Some types of MQTT Control Packets contain a variable header component. It resides between the fixed header and the payload. The content of the variable header varies depending on the Packet type. The Packet Identifier field of variable header is common in several packet types.
Packet Identifier
- non-zero
2 bytes
longer. - These Control Packets are PUBLISH (where QoS > 0), PUBACK, PUBREC, PUBREL, PUBCOMP, SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK.
- non-zero
3. Payload
- Some MQTT Control Packets contain a payload as the final part of the packet.
Control Packet Payload
CONNECT Required
CONNACK None
PUBLISH Optional
PUBACK None
PUBREC None
PUBREL None
PUBCOMP None
SUBSCRIBE Required
SUBACK Required
UNSUBSCRIBE Required
UNSUBACK None
PINGREQ None
PINGRESP None
DISCONNECT None
MQTT Control Packets
-
CONNECT
client
request for connection toserver
.- After network connection is established from client to server, the first packet to send from client side MUST be this.
client
can only send 1 CONNECT packet per network connection.Fixed Header
7th 6th 5th 4th
->0 0 0 1
3rd 2nd 1st 0th
->0 0 0 0
Remaining Length
Variable Header
Protocol Name
- This is UTF-8 encoded string value.
- Possible Values:
MQTT
for 3.1.1
Protocol Level
1 byte
containing the version of mqtt.- for latest, it is
4
.
Connect Flags
1 byte
contains all the required connect flags.7th bit
->username
6th bit
->password
5th bit
->will retain
4th 3rd bits
->Will QoS
2nd bit
->Will Flag
1st bit
->Clean Session
0th bit
->Reserved
Keep alive
2 bytes
contains information about keep alive.- This is time value in
seconds
.
Payload
Client ID
->UTF-8
encoded unique string.Will Topic
- if
will flag
is1
. - UTF-8 encoded string.
- if
Will Message
- if
will flag
is1
. - UTF-8 encoded string.
- if
Username
- if
username flag
is1
. - UTF-8 encoded string.
- if
Password
- if
password flag
is1
. - UTF-8 encoded string.
- if
-
CONNACK
- Acknowledge connection request
Fixed Header
- is
0 0 1 0 0 0 0 0
.
- is
Remaining Length
- is
0 0 0 0 0 0 1 0
.
- is
Variable header
1st byte
is0 0 0 0 0 0 0 SP
, whereSP
isSession Present
.2nd byte
isReturn Code
.-
0 0x00 Connection Accepted 1 0x01 Connection Refused, The Server does not support the level of the MQTT protocol requested by the Client 2 0x02 Connection Refused, identifier rejected The Client identifier is correct UTF-8 but not allowed by the Server 3 0x03 Connection Refused, Server unavailable 4 0x04 Connection Refused, bad user name or password 5 0x05 Connection Refused, not authorized 6 - 255 Reserved.
-
-
PUBLISH
- Packet is used when
client
wants to send data toserver
, orserver
wants to send data toclient
. Fixed Header 1st byte
7th 6th 5th 4th bits
->0 0 1 1
, This is the message type.3rd bit
->DUP Flag
,- if DUP = 0, this is first attempt to send message from client or server. if DUP = 1, then this might be re-attempt to send the message.
- for QoS = 0, DUP will always be 0.
2nd 1st buts
->Qos Level
- 0, 1, 2 values.
1st bit
-> 'RETAIN Flag'- When this is 1, we will store this message and will publish to all new subscribers just after subscription is finished.
Remaining Length 2nd.. bytes
Variable header
Topic Name
-> sort of key of the message that we are trying to publish,UTF-8
.PacketID
->u16
packet id to id the message.
Payload
- The type of data in payload is application specific.
- If
Qos = 0
forPUBLISH
packet, then there won't be any response from receiver to sender.
- Packet is used when
-
PUBACK
- This packet is sent from receiver to sender when
Qos = 1
inPUBLISH
packet. Fixed Header
0 1 0 0 0 0 0 0
Remaining Length
0 0 0 0 0 0 1 0
Variable Header
PacketId
-> 2 bytes
- No Paylaod.
- This packet is sent from receiver to sender when
-
PUBREC
- When
Qos=2
inPUBLISH
, receiver will sendPUBREC
packet to sender. Fixed Header
0 1 0 1 0 0 0 0
Remaining Length
0 0 0 0 0 0 1 0
Variable header
PacketID
-> This is the packet id we received from publish packet.
- no payload.
- When
-
PUBREL
- This is the response to
PUBREC
packet. sent from sender to receiver after sender receivesPUBREC
from receiver. Fixed Header
0 1 1 0 0 0 1 0
Remaing Length
0 0 0 0 0 0 1 0
Variable Header
PacketId
-> same packet id, which was received at the time ofPUBREC
.
- no payload.
- This is the response to
-
PUBCOMP
- This is the response to
PUBREL
packet. sent from receiver to sender after receiver receivesPUBREL
from sender. Fixed Header
0 1 1 1 0 0 1 0
Remaing Length
0 0 0 0 0 0 1 0
Variable Header
PacketId
-> same packet id, which was received at the time ofPUBREL
.
- no payload.
- This is the response to
-
SUBSCRIBE
- This packet is sent from
client
toserver
to createsubscription
. - Each subscription registers client's interest for one or more
topics
. - This is used when server wants to send
PUBLISH
packets to client. Subscribe
packet also describeMAX QoS
with which server can send packets to client.Fixed Header
1 0 0 0 0 0 1 0
Remaining Length 2nd.. bytes
Variable Header
PacketID
-> unique u16 id to identify the packet.
Payload
- List of
Topic Filters
plusQoS
. Where topic filters must be UTF-8 encoded strings.
- List of
- This packet is sent from
-
SUBACK
- Sent from server to client to confirm the subscription for client on perticular topic filter.
- This contains list of return codes, that spacifies the max QoS was granted in each subscription.
Fixed Header
1 0 0 1 0 0 0 0
Remaining Length
- Length of variable header + payload.
Variable Header
- Packet ID
Payload
- The payload contains a list of return codes. Each return code corresponds to a Topic Filter in the SUBSCRIBE Packet being acknowledged.
Allowed return codes: 0x00 - Success - Maximum QoS 0 0x01 - Success - Maximum QoS 1 0x02 - Success - Maximum QoS 2 0x80 - Failure ```
-
UNSUBSCRIBE
- Sent from
client
toserver
to remove interest from one or more topics. Fixed Header
1 0 1 0 0 0 1 0
Remaining Length
Variable Header
- Packet ID
Payload
- List of topic filters client want to unscribe to.
- Topics must be UTF-8 encoded strings.
- Sent from
-
UNSUBACK
- The UNSUBACK Packet is sent by the
Server
to theClient
to confirm receipt of an UNSUBSCRIBE Packet. Fixed Header
1 0 1 1 0 0 0 0
Remaining Length
Variable Header
- Packet ID received from unsubscribe request.
- No Payload.
- The UNSUBACK Packet is sent by the
-
PINGREQ
- The PINGREQ Packet is sent from a Client to the Server.
- Indicate to the Server that the Client is alive in the absence of any other Control Packets being sent from the Client to the Server.
- Request that the Server responds to confirm that it is alive.
- Exercise the network to indicate that the Network Connection is active.
Fixed Header
1 1 0 0 0 0 0 0
- remaining length is 0.
- Has no payload or variable headers.
-
PINGRESP
- A PINGRESP Packet is sent by the Server to the Client in response to a PINGREQ Packet. That indicates that server is alive.
Fixed Header
1 1 0 1 0 0 0 0
- remaining length is 0.
- Has no payload or variable headers.
-
DISCONNECT
- The DISCONNECT Packet is the final Control Packet sent from the Client to the Server. This indicates that client is disconnecting cleanly.
Fixed Header
1 1 1 0 0 0 0 0
- remaining length is 0.
- Has no payload or variable headers.
- After sending this packet, client must close the network connection, and not send any more control packets.
- server should close the client connection, if client failed to do so, and not accept any new packets from the client.
Dependencies
~115KB