Developing MQTT-SN Clients Guide

Introduction

Developing MQTT-SN Clients guide 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.

Getting Started

Machine-to-Machine, Machine-to-User, Machine-to-Mobile communication cannot happen without a powerful central server. MQTT edge devices and applications communicate via the MQTT Broker which acts as the central server. You can download the Enterprise MQTT Broker which can be run on Windows, Linux, Mac and Raspberry Pi now and get started..

Benefits over MQTT

The main advantage of the SN is packet size reduction and connectionless to make sure the transaction takes lesser energy. The 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 id can be used in the publish. This reduces the packet size to a greater extent.
  • Predefined Topic Names help you define all your topics in the gateway. The topic id of these topics can be used directly. Similarly, short topic names that are less than 2 bytes can be used directly without topic id.
  • Discovery is one of the major advantages of MQTT-SN. The clients need not know the IP address or the DNS Name of the Gateway or the broker to get started. The advertising/gateway discovery will help achieve it seamlessly.
  • The Clean Session is extended to WILL details where WILL details will persist like a client’s Subscriptions.
  • The Sensors can sleep after informing the gateway for a specific time. The gateway/server will buffer the messages intended for the particular client while it is in sleep and send it when the client wakes up.

Message structure

Fixed Header

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

Variable Header

TopicIdType

CleanSessionWillRetainQoSDUP

0, 1

2

3

4

5,6

7

The DUP, Retain, WILL, CleanSession are the 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,6th 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 needs to broadcast a searchgw packet to find the address of a gateway.

Structure of a searchgw packet

  1. This message is three bytes long. The first byte is the length. The second byte is the 0x01 message type. The third byte is the radius of the broadcast which has to be set on the underlying network also.
  2. This message has to be broadcasted into the network in a time interval and it will get a reply message as GWINFO.
    • The GWINFO message will be different by who sent the message.
    • If it’s sent by a Gateway it will be 3 bytes 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 knows 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 the WILL. The response will be a will topic request.

CONNECT

  • It is sent by a client to set up a connection to the gateway.
  • It has the following structure

Length

MsgType (0x04)FlagsProtocol IdDurationClientid

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 has to sent This Will Topic Packet.

Length

MsgType (0x07)FlagsWill 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 an MQTT-SN packet 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 a predefined 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 the 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)TopicidMsgidTopicName

0

1

2,3

4,5

5-N

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

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

RegAck

Length

Msgtype(0x0B)Topic idMsgidReturn Code

0

1

2, 3

4, 5

6

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

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 the register packet again.

Publish

Length

MsgType(0x0C)FlagsTopicIdMsgIdData

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 the same as subscribe. The packet structure of subscribe and unsubscribe is given below

Structure

Length

MsgType (subscribe (0x12) / unsubscribe (0x14))FlagsMsgIdTopicId or Topic Name

0

1

2

3, 4

5, 6 or 5-N

The Subscribe packet will have a variable length if it Subscribes using TopicName otherwise 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 acts as same as MQTT.

Disconnect with sleep

The client will send a disconnect message with 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 receives a ping resp if the buffer is empty. The client has to send a ping before the specified period or the gateway will consider as a lost client.

Length

MsgType (0x18)Duration(Optional)

0

1

2-3

WILL Topic and Message

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

WILLTOPICUPD

Length

MsgType(0x1A)FlagsWill Topic

0

1

2

3-N

The Flag will have QoS and retain.

A Will Topic response message will be sent as a response 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 addition to the acknowledgments it sends.

  1. Advertise packet
  2. SearchGW
  3. Register

Advertise Packet

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

SearchGW

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

Register

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