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 publish subscribe messaging protocols ( MQTT for sensor networks) as per Oasis standard by MQTT technical committee.

MQTT-SN is a protocol version that helps you create IoT sensor agents for low energy consuming IoT devices. The MQTT-SN protocol (SN MQTT for sensor) can be programmed to communicate over embedded devices on non TCP/IP networks such as zigbee , Bluetooth , z-wave , or any other medium including wired and wireless sensor networks. This protocol does not need a connected environment much like MQTT. But any bi-directional & lossy network protocols support MQTT and MQTT-SN. MQTT SN specification is available at mqtt.org.

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 and Linux 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.
Pre defined Topic IDs / 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. That’s why it has low processing power which makes it suitable for battery powered sensor.
MQTT-SN does not depend on TCP/IP networks to operate and it is over UDP. This minimizes the data transfer volume and the power required.
Unlike MQTT, MQTT-SN supports four types of QoS ( Quality of service ), QoS 0,1,2,-1 or 3 whereas MQTT supports QoS 0,1,2.

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	CleanSession	Will	Retain	QoS	DUP
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 Topic id 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 needs to broadcast a searchgw packet to find the address of a gateway. Also, a Client Can connect directly if it knows the address of a MQTT-SN 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.

Sensor Connect

The Client can be connected in 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

Length	MsgType (0x07)	Flags	Will topic
0	1	2	3-N

Will message

After setting a will topic successfully, 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)	Topicid	Msgid	TopicName
0	1	2,3	4,5	5-N

The Topic ID 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)	Topicid	Msgid	TopicName
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.

Length	MsgType(0x0C)	Flags	Topicid	Msgid	Data
0	1	2	3,4,	5,6	7

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))	Flags	MsgId	TopicId or Topic Name
0	1	2	3,4	5,6,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 message protocol.

WILLTOPICUPD

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(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 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

Miscellaneous

The client has to keep track of the following messages in addition to the acknowledgements it sends.

1.Advertise packet

2.SearchGW

3.Register

Advertise Packet

The 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.

Frameworks

Industry 4.0

MQTT