Introduction

This document provides a step by step getting started guide for developing iot device agents using MQTT-SN Protocol.

MQTT-SN is a protocol version that helps you create iot sensor agents for low energy consuming iot devices. The MQTT-SN protocol can be programmed to communicate over bluetooth, zigbee, z-wave or any other medium. This protocol does not need a connected environment much like MQTT.

Benefits over MQTT

The main advantage of the SN is the packet size reduction and connection less to make sure the transaction takes lesser energy. Following are the technical benefits / differences of using MQTT-SN over MQTT.

  • The WILL message is optional and can be sent as a separate packet. The MQTT-SN has divided the CONNECT message into three messages. You can just send the connect packet alone if you are not setting WILL Topic and Message.
  • The long topic names need not be sent with every message. Instead the topic ids can be used in the publish. This reduce the packet size to a greater extent.
  • Predefined Topic Names help you define all your topics in the gateway. The topic ids of these topics can be used directly. Similary, short topic names which are less than 2 bytes can be used directly without topic id.
  • Discovery is one of the major advantate of the MQTT-SN. The clients need not know the IP address or the DNS Name of the Gateway or the broker to get started. The advertise / gateway discovery will help achieve it seemlessly.
  • The Clean Session is extended to Will details where will details will persist like a clients Subscriptions.
  • The Sensors can sleep after informing the gateway for a specific period of time. The gateway/server will buffer the messages intended for the particular client while it is in sleep and send it when the client wake up.

Message structure

Fixed Header

  • The first byte of a MQTT-SN Fixed Header is length of The message
  • The second byte is the message type.The length will be considered from 0 byte.

Variable Header

TopicIdType

CleanSession Will Retain QoS DUP

0, 1

2

3

4

5,6

7

The DUP, Retain, WILL, CleanSession are same as MQTT.

  • They will be set to 0 or one by need.

The 0 and 1’st bit of Flag Will be used to specify the Topicid type.

  • For a Normal Topic the 0, 1 bit will be 00
  • For a Predefined Topic id 0, 1 bit will be 01
  • For a Short Topic name 0, 1 bit will be 10

The 5,6 th bit will be used to specify the QoS.

  • For QoS 0 - 5, 6 bit has to be 00
  • For QoS 1 - 5, 6 bit has to be 01
  • For QoS 2 -5, 6 bit has to be 10
  • For QoS -1 -5, 6 bit has to be 11

Gateway Discovery

A new client on a network need to broadcast a searchgw packet to find the address of a gateway.

Structure of a searchgw packet

  1. This message is three bytes long. First byte is length. Second byte is message type which is 0x01. Third byte is radius of broadcast which has to be set on underlying network also.
  2. This message has to be broadcasted into the network in a time intervel and it will get a reply message as GWINFO.
    • The GWINFO message will be differ by who sent the message.
    • If its sent by a Gateway it will be 3 byte long and if it’s sent by another SN_CLIENT it will have a variable length containing the address of a gateway.
    A Client Can also connect directly if it know the address of a gateway.

Sensor Connect

The Client Can connect by two methods

  1. Connecting without will. The response will be connack message
  2. Connecting with will. The response will be a will topic request.

CONNECT

  • It is sent by a client to setup a connection to the gateway.
  • It has the Following structure

Length

MsgType (0x04) Flags Protocol Id Duration Clientid

0

1

2

3

4,5

6-N

Will topic

The Gateway will send will Topic request message if will flag is set in the connect message and the Client have to sent This Will Topic Packet.

Length

MsgType (0x07) Flags Will topic

0

1

2

3-N

Will message

After a successful will topic is set the gateway will send a will message request and the client has to send The will message.

Length

Msgtype (0x09) Willmsg

0

1

2-N

Publish

There are four ways in which a MQTT-SN packate can be published.

Using registered Topic Id - The client has to register the topic name with the gateway and then start publishing using the received topic id.

Using Short Topics - The client can directly publish using a topic name when the length of the topic name is less than 2 bytes.

Using Predefined Topics - The gateway will have predefiend topic whose topic id can be used by the client to publish. The predefined topic id in which the topic id of a topic is known for both server and client so there is no need to register

Adhoc Topic - This is a special one where the client does not have to create a connection to the gateway it can simply start publishing by setting QoS flag to -1 no connection establishment or termination the gateway will maintain a separate mqtt connection to the broker to handle this kind of publish. In QoS -1 publish the client can only use predefined topic id or short topic name ,there is no connection setup so registering topic is not possible

Packet Structure for the Register and publishing are as follows.

Register

Length

Msgtype(0x0A) Topicid Msgid TopicName

0

1

2,3

4,5

5-N

The Topicid has to coded as 0 when the register message is sent by client.

The Client can get the topic id from regack using the following packet structure.

RegAck

Length

Msgtype(0x0B) Topic id Msgid Return Code

0

1

2, 3

4, 5

6

The client has to match appropriate REGACK message to the register packet by using messageid.

The Client has to check the return code of REGACK and if its 0 the client can use the Topic id otherwise it has to Sent register packet again.

Publish

Length

MsgType(0x0C) Flags TopicId MsgId Data

0

1

2

3, 4

5, 6

7-N

Subscribe / Unsubscribe

A client can use topic id to subscribe to a topic if it is previously registered to a topic. It can use the topic name or short topic name to subscribe. It will receive a suback message with topic id. The unsubscribe packet is same as subscribe. The packet structure of subscribe and unsubscribe is given below

Structure

Length

MsgType (subscribe (0x12) / unsubscribe (0x14)) Flags MsgId TopicId or Topic Name

0

1

2

3, 4

5, 6 or 5-N

The Subscribe packet will have variable length if it Subscribe using TopicName otherwise the it will be 7 bytes.

Sensor Disconnect

There are two ways in which a client can disconnect from the gateway.

Disconnect permanently

The client has to send a disconnect packet to disconnect permanently.it act as same as mqtt

Disconnect with sleep

The client will send disconnect message with a time duration and go to sleep for that time duration the gateway will buffer the messages for that client during this time period. The client has to send a ping message to get the buffered message and it will receive publish messages from the buffer. The client receive a ping resp if the buffer is empty. The client has to send ping before the specified period or the gateway will consider as a lost client.

The packet structure of disconnect

Length

MsgType (0x18) Duration(Optional)

0

1

2-3

WILL Topic & Message

The MQTT-SN has a provision to update the WILL Topic and message at any point of time. This is an advanaced functionality over the MQTT.

WILLTOPICUPD

Length

MsgType(0x1A) Flags Will Topic

0

1

2

3-N

The Flag will have qos and retain.

A Will Topic response message will be sent as a responce in the following structure

Length

MsgType(willtopicresp (0x1B) / willmessageresp (0x1D)) ReturnCode

0

1

2

If the Return Code is other than 0 it has to resend The Willtopicupd.

WILLMSGUPD

Length

MsgType(0x1C) WillMsg

0

1

2-N

The Client will receive a Willmsgresp for similar packet format to willtopicresp.

Miscellaneous

The client has to keep track of the following messages in additions to the acknowledgements it send.

  1. Advertise packet
  2. SearchGW
  3. Register

Advertise Packet

The gateways on the network will send advertise packet in a certain period of time. The client has to maintain the list of active gateways in the network by the advertise duration.

SearchGW

The client has to respond to a searchgw message by broadcasting gwinfo message. It has to send a active gateway address from it gateway address list

Register

If a client is reconnected it will receive register message with topic name and topic id for its previous registrations and subscription it has to store the topic name and ids.