MQTT.js is a client library for the MQTT protocol, written in JavaScript for node.js and the browser.
MQTT.js is an OPEN Open Source Project, see the Contributing section to find out what this means.
v1.0.0 improves the overall architecture of the project, which is now splitted in three components: MQTT.js keeps the Client, mqtt-connection includes the barebone Connection code for server-side usage, and mqtt-packet includes the protocol parser and generator. The new Client improves performance by a 30% factor, embeds Websocket support (MOWS is now deprecated), and it has a better support for QoS 1 and 2. The previous API is still supported but deprecated, as such, it id not documented in this README.
As a breaking change, the encoding option in the old client is
removed, and now everything is UTF-8 with the exception of the
password in the CONNECT message and payload in the PUBLISH message,
which are Buffer.
Another breaking change is that MQTT.js now defaults to MQTT v3.1.1, so to support old brokers, please read the client options doc.
npm install mqtt --saveFor the sake of simplicity, let's put the subscriber and the publisher in the same file:
var mqtt = require('mqtt');
var client = mqtt.connect('mqtt://test.mosquitto.org');
client.on('connect', function () {
client.subscribe('presence');
client.publish('presence', 'Hello mqtt');
});
client.on('message', function (topic, message) {
// message is Buffer
console.log(message.toString());
client.end();
});output:
Hello mqtt
If you want to run your own MQTT broker, you can use Mosquitto or Mosca, and launch it. You can also use a test instance: test.mosquitto.org and test.mosca.io are both public.
If you do not want to install a separate broker, you can try using the server/orig example. It implements enough of the semantics of the MQTT protocol to run the example.
to use MQTT.js in the browser see the browserify section
MQTT.js bundles a command to interact with a broker. In order to have it available on your path, you should install MQTT.js globally:
npm install mqtt -gThen, on one terminal
mqtt sub -t 'hello' -h 'test.mosquitto.org' -v
On another
mqtt pub -t 'hello' -h 'test.mosquitto.org' -m 'from MQTT.js'
See mqtt help <command> for the command help.
mqtt.connect()mqtt.Client()mqtt.Client#publish()mqtt.Client#subscribe()mqtt.Client#unsubscribe()mqtt.Client#end()mqtt.Client#handleMessage()mqtt.Store()mqtt.Store#put()mqtt.Store#del()mqtt.Store#createStream()mqtt.Store#close()
Connects to the 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.
For all MQTT-related options, see the Client constructor.
The Client class wraps a client connection to an
MQTT broker over an arbitrary transport method (TCP, TLS,
WebSocket, ecc).
Client automatically handles the following:
- Regular server pings
- QoS flow
- Automatic reconnections
- Start publishing before being connected
The arguments are:
streamBuilderis a function that returns a subclass of theStreamclass that supports theconnectevent. Typically anet.Socket.optionsis the client connection options (see: the connect packet). Defaults:keepalive:10seconds, set to0to disableclientId:'mqttjs'_ + crypto.randomBytes(16).toString('hex')protocolId:'MQTT'protocolVersion:4clean:true, set to false to receive QoS 1 and 2 messages while offlinereconnectPeriod:1000milliseconds, interval between two reconnectionsincomingStore: a Store for the incoming packetsoutgoingStore: a Store for the outgoing packetswill: a message that will sent by the broker automatically when the client disconnect badly. The format is:topic: the topic to publishpayload: the message to publishqos: the QoSretain: the retain flag
In case mqtts (mqtt over tls) is required, the options object is
passed through to
tls.connect().
If you are connecting to a broker that supports only MQTT 3.1 (not 3.1.1 compliant), you should pass these additional options:
{
protocolId: 'MQIsdp',
protocolVersion: 3
}This is confirmed on RabbitMQ 3.2.4, and on Mosquitto < 1.3. Mosquitto version 1.3 and 1.4 works fine without those.
function() {}
Emitted on successful (re)connection (i.e. connack rc=0).
function() {}
Emitted after a disconnection.
function() {}
Emitted when the client goes offline.
function(error) {}
Emitted when the client cannot connect (i.e. connack rc != 0) or when a parsing error occurs.
function(topic, message, packet) {}
Emitted when the client recieves a publish packet
topictopic of the received packetmessagepayload of the received packetpacketreceived packet, as defined in mqtt-packet
Publish a message
topicis the topic to publish to,Stringmessageis the message to publish,BufferorStringoptionsis the options to publish with, including:qosqos level, default0retainretain flag, defaultfalse
callbackcallback fired when the QoS handling completes, or at the next tick if QoS 0.
Subscribe to a topic or topics
topicis aStringtopic to subscribe to or anArrayof topics to subscribe to. It can also be an object, it has as object keys the topic name and as value the QoS, like{'test1': 0, 'test2': 1}.optionsis the options to subscribe with, including:qosqos subscription level, default 0
callback-function(err, granted)callback fired on suback where:erra subscription errorgrantedis an array of{topic, qos}where:topicis a subscribed to topicqosis the granted qos level on it
Unsubscribe from a topic or topics
topicis aStringtopic or an array of topics to unsubscribe fromcallbackfired on unsuback
Close the client, calls callback when finished.
Handle messages with backpressure support, one at a time.
Override at will, but always call callback, or the client
will hang.
In-memory implementation of the message store.
Another implementaion is mqtt-level-store which uses Level-browserify to store the inflight data, making it usable both in Node and the Browser.
Adds a packet to the store, a packet is
anything that has a messageId property.
The callback is called when the packet has been stored.
Creates a stream with all the packets in the store.
Removes a packet from the store, a packet is
anything that has a messageId property.
The callback is called when the packet has been removed.
Closes the Store.
In order to use MQTT.js as a browserify module you can either require it in your browserify bundles or build it as a stand alone module. The exported module is AMD/CommonJs compatible and it will add an object in the global space.
npm install -g browserify // install browserify
cd node_modules/mqtt
npm install . // install dev dependencies
browserify mqtt.js -s mqtt > browserMqtt.js // require mqtt in your client-side appyou can then use mqtt.js in the browser with the same api than node's one.
<html>
<head>
<title>test Ws mqtt.js</title>
</head>
<body>
<script src="./browserMqtt.js"></script>
<script>
var client = mqtt.connect(); // you add a ws:// url here
client.subscribe("mqtt/demo");
client.on("message", function(topic, payload) {
alert([topic, payload].join(": "));
client.end();
});
client.publish("mqtt/demo", "hello world!");
</script>
</body>
</html>Your broker should accept websocket connection (see MQTT over Websockets to setup Mosca).
MQTT.js is an OPEN Open Source Project. This means that:
Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.
See the CONTRIBUTING.md file for more details.
MQTT.js is only possible due to the excellent work of the following contributors:
| Adam Rudd | GitHub/adamvr | Twitter/@adam_vr |
|---|---|---|
| Matteo Collina | GitHub/mcollina | Twitter/@matteocollina |
MIT