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.
v2.0.0 removes support for node v0.8, v0.10 and v0.12, and it is 3x faster in sending
packets. It also removes all the deprecated functionality in v1.0.0,
mainly mqtt.createConnection
and mqtt.Server
. From v2.0.0,
subscriptions are restored upon reconnection if clean: true
.
v1.x.x is now in LTS, and it will keep being supported as long as
there are v0.8, v0.10 and v0.12 users.
v1.0.0 improves the overall architecture of the project, which is now
split into 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 is 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.
MQTT v5 support is experimental as it has not been implemented by brokers yet.
npm install mqtt --save
For 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', function (err) {
if (!err) {
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
mqtt-connection.
to use MQTT.js in the browser see the browserify section
If you want to use the new async-await functionality in JavaScript, or just prefer using Promises instead of callbacks, async-mqtt is a wrapper over MQTT.js which uses promises instead of callbacks when possible.
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 -g
Then, 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
for the command help.
mqtt.connect()
mqtt.Client()
mqtt.Client#publish()
mqtt.Client#subscribe()
mqtt.Client#unsubscribe()
mqtt.Client#end()
mqtt.Client#removeOutgoingMessage()
mqtt.Client#reconnect()
mqtt.Client#handleMessage()
mqtt.Client#connected
mqtt.Client#reconnecting
mqtt.Client#getLastMessageId()
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:
The arguments are:
streamBuilder
is a function that returns a subclass of the Stream
class that supportsconnect
event. Typically a net.Socket
.options
is the client connection options (see: the connect packet). Defaults:
wsOptions
: is the WebSocket connection options. Default is {}
.keepalive
: 60
seconds, set to 0
to disablereschedulePings
: reschedule ping messages after sending packets (default true
)clientId
: 'mqttjs_' + Math.random().toString(16).substr(2, 8)
protocolId
: 'MQTT'
protocolVersion
: 4
clean
: true
, set to false to receive QoS 1 and 2 messages whilereconnectPeriod
: 1000
milliseconds, interval between twoconnectTimeout
: 30 * 1000
milliseconds, time to wait before ausername
: the username required by your broker, if anypassword
: the password required by your broker, if anyincomingStore
: a Store for the incoming packetsoutgoingStore
: a Store for the outgoing packetsqueueQoSZero
: if connection is broken, queue outgoing QoS zero messages (default true
)customHandleAcks
: MQTT 5 feature of custom handling puback and pubrec packets. Its callback: customHandleAcks: function(topic, message, packet, done) {*some logic wit colling done(error, reasonCode)*}
properties
: properties MQTT 5.0.object
that supports the following properties:
sessionExpiryInterval
: representing the Session Expiry Interval in seconds number
,receiveMaximum
: representing the Receive Maximum value number
,maximumPacketSize
: representing the Maximum Packet Size the Client is willing to accept number
,topicAliasMaximum
: representing the Topic Alias Maximum value indicates the highest value that the Client will accept as a Topic Alias sent by the Server number
,requestResponseInformation
: The Client uses this value to request the Server to return Response Information in the CONNACK boolean
,requestProblemInformation
: The Client uses this value to indicate whether the Reason String or User Properties are sent in the case of failures boolean
,userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairs object
,authenticationMethod
: the name of the authentication method used for extended authentication string
,authenticationData
: Binary Data containing authentication data binary
authPacket
: settings for auth packet object
will
: a message that will sent by the broker automatically whentopic
: the topic to publishpayload
: the message to publishqos
: the QoSretain
: the retain flagproperties
: properties of will by MQTT 5.0:
willDelayInterval
: representing the Will Delay Interval in seconds number
,payloadFormatIndicator
: Will Message is UTF-8 Encoded Character Data or not boolean
,messageExpiryInterval
: value is the lifetime of the Will Message in seconds and is sent as the Publication Expiry Interval when the Server publishes the Will Message number
,contentType
: describing the content of the Will Message string
,responseTopic
: String which is used as the Topic Name for a response message string
,correlationData
: The Correlation Data is used by the sender of the Request Message to identify which request the Response Message is for when it is received binary
,userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairs object
transformWsUrl
: optional (url, options, client) => url
functionresubscribe
: if connection is broken and reconnects,true
)In case mqtts (mqtt over tls) is required, the options
object is
passed through to
tls.connect()
.
If you are using a self-signed certificate, pass the rejectUnauthorized: false
option.
Beware that you are exposing yourself to man in the middle attacks, so it is a configuration
that is not recommended for production environments.
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.
'connect'
function (connack) {}
Emitted on successful (re)connection (i.e. connack rc=0).
connack
received connack packet. When clean
connection option is false
and server has a previous sessionclientId
connection option, then connack.sessionPresent
flag is true
. When that is the case,'reconnect'
function () {}
Emitted when a reconnect starts.
'close'
function () {}
Emitted after a disconnection.
'disconnect'
function (packet) {}
Emitted after receiving disconnect packet from broker. MQTT 5.0 feature.
'offline'
function () {}
Emitted when the client goes offline.
'error'
function (error) {}
Emitted when the client cannot connect (i.e. connack rc != 0) or when a
parsing error occurs.
'end'
function () {}
Emitted when mqtt.Client#end()
is called.
If a callback was passed to mqtt.Client#end()
, this event is emitted once the
callback returns.
'message'
function (topic, message, packet) {}
Emitted when the client receives a publish packet
topic
topic of the received packetmessage
payload of the received packetpacket
received packet, as defined in'packetsend'
function (packet) {}
Emitted when the client sends any packet. This includes .published() packets
as well as packets used by MQTT for managing subscriptions and connections
packet
received packet, as defined in'packetreceive'
function (packet) {}
Emitted when the client receives any packet. This includes packets from
subscribed topics as well as packets used by MQTT for managing subscriptions
and connections
packet
received packet, as defined inPublish a message to a topic
topic
is the topic to publish to, String
message
is the message to publish, Buffer
or String
options
is the options to publish with, including:
qos
QoS level, Number
, default 0
retain
retain flag, Boolean
, default false
dup
mark as duplicate flag, Boolean
, default false
properties
: MQTT 5.0 properties object
payloadFormatIndicator
: Payload is UTF-8 Encoded Character Data or not boolean
,messageExpiryInterval
: the lifetime of the Application Message in seconds number
,topicAlias
: value that is used to identify the Topic instead of using the Topic Name number
,responseTopic
: String which is used as the Topic Name for a response message string
,correlationData
: used by the sender of the Request Message to identify which request the Response Message is for when it is received binary
,userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairs object
,subscriptionIdentifier
: representing the identifier of the subscription number
,contentType
: String describing the content of the Application Message string
cbStorePut
- function ()
, fired when message is put into outgoingStore
if QoS is 1
or 2
.callback
- function (err)
, fired when the QoS handling completes,Subscribe to a topic or topics
topic
is a String
topic to subscribe to or an Array
of{'test1': {qos: 0}, 'test2': {qos: 1}}
.topic
wildcard characters are supported (+
- for single level and #
- for multi level)options
is the options to subscribe with, including:
qos
qos subscription level, default 0nl
No Local MQTT 5.0 flag (If the value is true, Application Messages MUST NOT be forwarded to a connection with a ClientID equal to the ClientID of the publishing connection)rap
Retain as Published MQTT 5.0 flag (If true, Application Messages forwarded using this subscription keep the RETAIN flag they were published with. If false, Application Messages forwarded using this subscription have the RETAIN flag set to 0.)rh
Retain Handling MQTT 5.0 (This option specifies whether retained messages are sent when the subscription is established.)properties
: object
subscriptionIdentifier
: representing the identifier of the subscription number
,userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairs object
callback
- function (err, granted)
err
a subscription error or an error that occurs when client is disconnectinggranted
is an array of {topic, qos}
where:
topic
is a subscribed to topicqos
is the granted qos level on itUnsubscribe from a topic or topics
topic
is a String
topic or an array of topics to unsubscribe fromoptions
: options of unsubscribe.
properties
: object
userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairs object
callback
- function (err)
, fired on unsuback. An error occurs if client is disconnecting.Close the client, accepts the following options:
force
: passing it to true will close the client right away, withoutoptions
: options of disconnect.
reasonCode
: Disconnect Reason Code number
properties
: object
sessionExpiryInterval
: representing the Session Expiry Interval in seconds number
,reasonString
: representing the reason for the disconnect string
,userProperties
: The User Property is allowed to appear multiple times to represent multiple name, value pairs object
,serverReference
: String which can be used by the Client to identify another Server to use string
cb
: will be called when the client is closed. This parameter isRemove a message from the outgoingStore.
The outgoing callback will be called with Error(‘Message removed’) if the message is removed.
After this function is called, the messageId is released and becomes reusable.
mid
: The messageId of the message in the outgoingStore.Connect again using the same options as connect()
Handle messages with backpressure support, one at a time.
Override at will, but always call callback
, or the client
will hang.
Boolean : set to true
if the client is connected. false
otherwise.
Number : get last message id. This is for sent messages only.
Boolean : set to true
if the client is trying to reconnect to the server. false
otherwise.
In-memory implementation of the message store.
options
is the store options:
clean
: true
, clean inflight messages when close is called (default true
)Other implementations of mqtt.Store
:
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.
The MQTT.js bundle is available through http://unpkg.com, specifically
at https://unpkg.com/mqtt/dist/mqtt.min.js.
See http://unpkg.com for the full documentation on version ranges.
Support WeChat Mini Program. See Doc.
var mqtt = require('mqtt')
var client = mqtt.connect('wxs://test.mosquitto.org')
import { connect } from 'mqtt';
const client = connect('wxs://test.mosquitto.org');
Surport Ali Mini Program. See Doc.
var mqtt = require('mqtt')
var client = mqtt.connect('alis://test.mosquitto.org')
import { connect } from 'mqtt';
const client = connect('alis://test.mosquitto.org');
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 app
Just like browserify, export MQTT.js as library. The exported module would be var mqtt = xxx
and it will add an object in the global space. You could also export module in other formats (AMD/CommonJS/others) by setting output.libraryTarget in webpack configuration.
npm install -g webpack // install webpack
cd node_modules/mqtt
npm install . // install dev dependencies
webpack mqtt.js ./browserMqtt.js --output-library mqtt
you can then use mqtt.js in the browser with the same api than node’s one.
<html>
<head>
<title>test Ws mqtt.jstitle>
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).
If you need to sign an url, for example for AWS IoT,
then you can pass in a transformWsUrl
function to the mqtt.connect()
options
This is needed because signed urls have an expiry and eventually upon reconnects, a new signed url needs to be created:
// This module doesn't actually exist, just an example
var awsIotUrlSigner = require('awsIotUrlSigner')
mqtt.connect('wss://a2ukbzaqo9vbpb.iot.ap-southeast-1.amazonaws.com/mqtt', {
transformWsUrl: function (url, options, client) {
// It's possible to inspect some state on options(pre parsed url components)
// and the client (reconnect state etc)
return awsIotUrlSigner(url)
}
})
// Now every time a new WebSocket connection is opened (hopefully not that
// often) we get a freshly signed url
Here is how QoS works:
About data consumption, obviously, QoS 2 > QoS 1 > QoS 0, if that’s a concern to you.
This repo bundles TypeScript definition files for use in TypeScript projects and to support tools that can read .d.ts
files.
Before you can begin using these TypeScript definitions with your project, you need to make sure your project meets a few of these requirements:
{"compilerOptions" : {"moduleResolution" : "node"}, ...}
npm install --save-dev @types/node
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 |
Maxime Agor | GitHub/4rzael | Twitter/@4rzael |
Siarhei Buntsevich | GitHub/scarry1992 |
MIT