Getting started with MQTT6 min read

In this post, we will take a look at a communication protocol named Message Queue Telemetry Transport a.k.a. MQTT. MQTT is a lightweight, secure, battery friendly and a machine-to-machine (M2M)/”Internet of Things” connectivity protocol.

Andy Stanford-Clark and Arlen Nipper from Cirrus Link Solutions authored the first version of the protocol in 1999.

What is MQTT?

MQTT (formerly Message Queue Telemetry Transport) is a publish-subscribe based “light weight” messaging protocol for use on top of the TCP/IP protocol. It is designed for connections with remote locations where a “small code footprint” is required and/or network bandwidth is limited. The Publish-Subscribe messaging pattern requires a message broker. The broker is responsible for distributing messages to interested clients based on the topic of a message.

The specification does not specify the meaning of “small code foot print” or the meaning of “limited network bandwidth”. Thus, the protocol’s availability for use depends on the context. In 2013 IBM submitted MQTT v3.1 to the OASIS specification body with a charter that ensured only minor changes to the specification could be accepted. MQTT-SN is a variation of the main protocol aimed at embedded devices on non-TCP/IP networks, such as ZigBee.

Historically, the ‘MQ’ in ‘MQTT’ came from IBM’s MQ message queuing product line. However, queuing per se is not required to be supported as a standard feature in all situations.

Real world applications

Facebook Messenger : Facebook has used aspects of MQTT in Facebook Messenger. However, it is unclear how much of MQTT is used or for what; Moreover it is to be noted that this is a phone application not a sensor application.

Understanding OSI Model

To gain a better understanding of where MQTT fits, you need to have an understanding of the OSI model. If you already know about it, you can skip the below video.

MQTT is in the same layer as HTTP, Layer 7.


  1. It is a publish/subscribe protocol
  2. It has Multiple Quality of Service levels (QOS)
  3. It has at-least-once and exactly-once semantics
  4. It has a low overhead (2 bytes at minimum)
  5. It supports offline messaging
  6. It retains messages, like a key/value store

Matteo Collina, the author of Mosca, gave a nice talk on what MQTT is and how it works well with Node.

You can find a copy of his presentation on MQTT and Node.js here.

Where will MQTT fit in?

Imagine the below environment


where the status/sensor readings of a single machine/device needs to be transmitted to another machine/device, and a real time dashboard and a tablet or a wearable. Hooking up and maintaining data across so many devices may be tricky. This is where MQTT fits in well.

Hands on

Now that we have a fair understanding of MQTT, we will try out a simple example. We will be implementing a server/broker which will take in data and distribute it to all its clients using Mosca. And then we will implement a MQTT client using MQTT.js that publishes and subscribes to topics via the broker.

Create a new folder named mqttApp. We will create 2 new folders inside it named server and client.

Open a new terminal/prompt inside the server folder. Create a new Node.js project by running

npm init

Fill it up as applicable. Next, we will install Mosca as a dependency and save it. Run

npm install mosca --save

Create another file named server.js inside the server folder. Update it as below

A simple MQTT broker. Things to notice

Line 1 : Include Mosca

Line 3 : Configure the server

Line 8 : Start the server

Line 12 : The call back when the server is started

Line 17 : clientConnected : when a client is connected; the client is passed as a parameter.

Line 22 : published : when a new message is published; the packet and the client are passed as parameters.

Line 27 : subscribed : when a client is subscribed to a topic; the topic and the client are passed as parameters.

Line 32 : unsubscribed : when a client is unsubscribed to a topic; the topic and the client are passed as parameters.

Line 37 : clientDisconnecting : when a client is being disconnected; the client is passed as a parameter.

Line 42 : clientDisconnected : when a client is disconnected; the client is passed as a parameter.

Simple pub/sub API.

If you want to enable the offline mode, we need to store the data into one of the Key value pair storages. Out of the box Mosca supports most of the popular key value pair datastores. Below is a quick example how you can use it with MongoDB.

Updated server.js.

The only thing that changed is line 3. We have added the MongoDB settings here. (You can use a service like Mongo Lab to store the data on the cloud.) And then we include these settings on line 12.

Before we start the server, we need to start the MongoDB instance. If you are new to MongoDB, take a look at this.

Once MongoDB is started, we will start the server by running

node server.js

If MongoDB is started and running, you should see the success message. Else you will see a stack of error.

This is a simple broken server with offline capabilities. Before we go further, we will update our server to work as a real time broker. Update server.js  as below

Here we hook a callback to the server published event and then build a new packet on every message received and then send the new packet to the client.

Now, we will build a MQTT client that can pub/sub to topics. Open a new terminal/prompt inside the client folder.

Our client will be another Node.js application. In this example, both are running on the same machine. But in real time, the client application will be deployed on an actual device like a Pi or a Arduino. And the server would be on the cloud.

Now, run

npm init

Fill it up as applicable. MQTT.js would be a dependency here. Run

npm install mqtt --save

Create a new file named client1.js inside the client folder. We will emulate 2 clients on our local machine to see how things work. Update client1.js as below

Things to notice

Line 1 : We require MQTT

Line 3 : We connect to the server

Line 5 : We subscribe to a topic named “presence”

Line 8 : We publish a message to “presence”

Line 10 : We close the close the client

We will create another client that will listen for changes in the “presence” topic. Create a new file inside client folder and name it as client2.js. Update it as below

Same as client1.js except this client only listens to changes.

To test this, We will first start the server. Run

node server.js

And you should see the server started log. Next, client 2, Run

node client2.js

You should see the client started log. And finally client 1, Run

node client1.js

And the server console should reflect

Screen Shot 2014-10-22 at 7.54.29 pmThe last packet is our presence topic. And the client2 console should look like

Screen Shot 2014-10-22 at 7.55.07 pmSimple and easy communication with MQTT protocol!

You can find the complete code in the example here.

Also do checkout this awesome video by Matteo Collina where he Live Codes a Robot and control it from the web – LXJS 2014

Hope this post gave you an ideas as how to implement MQTT in Node.js

Special thanks to Matteo Collina for reviewing this article

Thanks for reading! Do comment.