MQTT.js - MQTT Client Library Encyclopedia
The MQTT.js provides a full-featured Javascript library for the MQTT protocol. It is fully isomorphic, which means it can run in the browser and in node.js (>= 0.8), including Intel Edison and Raspberry PIs. In fact, it is bundled in base image of the Intel Edison.
The library was originally written by Adam Rudd in May 2011, and it has been upgraded to all versions of node.js since then. In 2014, Matteo Collina took over as a maintainer, and since version 1.0.0 it supports MQTT over Websockets, both in Node.js and in the Browser.
Overview of MQTT.js MQTT Client Library
MQTT.js | |
---|---|
Language | Javascript |
License | MIT |
Website | github.com/mqttjs/MQTT.js |
API Style | Asynchronous, Callbacks, Streams, Offline |
This library is production ready and used by some fortune 500 companies. It can support long running clients with spotty connectivity. It has an optional on-disk storage for local offline messaging. MQTT.js became Open Open Source last January, and it had 55 contributors in its history. There is a team of 4 that maintains the library.
Features Supported by MQTT.js MQTT Client Library
Feature | |
---|---|
MQTT 3.1 | Yes |
MQTT 3.1.1 | Yes |
LWT | Yes |
SSL/TLS | Yes |
Automatic Reconnect | Yes |
Advanced Features: MQTT.js MQTT Client Library
Feature | Yes |
---|---|
QoS 0 | Yes |
QoS 1 | Yes |
QoS 2 | Yes |
Authentication | Yes |
Throttling | limited |
How to Use MQTT.js MQTT Client Library
Installation
You need node.js installed to use MQTT.js, then:
npm install mqtt
If you want to use the embedded CLI tools, you need to
npm install mqtt -g
Connecting to an MQTT Broker While Using MQTT.js MQTT Client Library
mqtt.connect([url], options)
Connects to the MQTT broker specified by the given url and options and returns a Client.
The URL can be on the following protocols: ‘mqtt’, ‘mqtts’, ’tcp’, ’tls’, ‘ws’, ‘wss’
. The URL can also be an object as returned by URL.parse()
, in that case the two objects are merged, i.e. you can pass a single object with both the URL and the connect options.
You can also specify a servers options with content: [{ host: 'localhost', port: 1883 }, ... ]
, in that case that array is iterated at every connect.
var mqtt = require('mqtt');
var client = mqtt.connect('mqtt://broker.mqttdashboard.com');
Connect with MQTT 3.1 or MQTT 3.1.1
The library connects with MQTT 3.1.1 by default. To connect with MQTT 3.1
var mqtt = require('mqtt');
var client = mqtt.connect('mqtt://broker.mqttdashboard.com',{
protocolId: 'MQIsdp',
protocolVersion: 3
});
Connect with LWT
LWT can be set in the connect function, like the following:
var mqtt = require('mqtt');
var client = mqtt.connect('mqtt://broker.mqttdashboard.com',{
will: {
topic: 'dead',
payload; 'mypayload',
qos: 1,
retain: true
}
});
Connect with Username/Password
Username and password can be set in the connect function, like the following:
var mqtt = require('mqtt');
var client = mqtt.connect('mqtt://broker.mqttdashboard.com',{
username: 'myuser',
password: 'mypassword'
});
Publishing an MQTT Message Using MQTT.js MQTT Client Library
mqtt.Client#publish(topic, message, [options], [callback])
Publish a message to a topic.
topic
is the topic to publish to,String
message
is the message to publish,Buffer
orString
options
are the options to publish with, including:qos
QoS level,Number
, default0
retain
retain flag,Boolean
, defaultfalse
callback
callback fired when the QoS handling completes, or at the next tick if QoS 0.
Subscribing to an MQTT Topic Using MQTT.js MQTT Client Library
mqtt.Client#subscribe(topic/topic array/topic object, [options], [callback])
Subscribe to a topic or topics
topic
is aString topic
to subscribe to or anArray of topics
to subscribe to. It can also be anobject
, the objectkey
is thetopic name
and thevalue
is theQoS
, like{'test1': 0, 'test2': 1}
.options
is the options to subscribe with, including:qos
qos subscription level,default 0
callback
-function(err, granted)
callback fired on suback where:err
is asubscription error
granted
is anarray of {topic, qos}
where:topic
is asubscribed to topic
qos
is thegranted qos level
on it
client.subscribe(‘presence');
client.on('message', function (topic, message) {
// message is Buffer
console.log(message.toString());
client.end();
});
Unsubscribing to an MQTT Topic While Using MQTT.js MQTT Client Library
mqtt.Client#unsubscribe(topic/topic array, [options], [callback])
Unsubscribe from a topic or topics
topic
is a String topic
or an array of topics
to unsubscribe from callback
fired on unsuback
Disconnect
Using SSL / TLS
The user should call mqtt.connect(), here is a full example:
var mqtt = require('mqtt');
var fs = require('fs');
var KEY = __dirname + '/tls-key.pem';
var CERT = __dirname + '/tls-cert.pem';
var TRUSTED_CA_LIST = [__dirname + '/crt.ca.cg.pem'];
var PORT = 1883;
var HOST = 'stark';
var options = {
port: PORT,
host: HOST,
keyPath: KEY,
certPath: CERT,
rejectUnauthorized : true,
//The CA list will be used to determine if server is authorized
ca: TRUSTED_CA_LIST
};
var client = mqtt.connect(options);
client.subscribe('messages');
client.publish('messages', 'Current time is: ' + new Date());
client.on('message', function(topic, message) {
console.log(message);
});
client.on('connect', function(){
console.log('Connected');
});

Matteo Collina
Matteo is a code pirate and mad scientist. He spends most of his days programming in node.js, but in the past he worked with Ruby, Java and Objective-C. He recently got a Ph.D. with a thesis titled "Application Platforms for the Internet of Things". Now he is a Software Architect at nearForm, where he consults for the top brands in world. Matteo is also the author of the Node.js MQTT Broker, Mosca and of the LevelGraph database. Matteo spoke at several international conferences: NodeSummit, Nodeconf.eu, LXJS, Distill by Engine Yard, and JsDay to name a few. He is also co-author of the book "Javascript: Best Practices" edited by FAG, Milan. In the summer he loves sailing the Sirocco.