Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
This branch is 4 commits ahead of dvdbng:master.

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


MQTT/WebSocket bridge. Runs as a WebSocket server and connects to an MQTT server. WebSocket clients subscribe to an MQTT topic by specifying the topic as part of the WebSocket URL (see below). The client would then begin receiving data on the topic through the connection, and could even publish by sending data on the WS connection.

You can also subscribe to wildcard topics the same way (URL encoded, of course), but you won't be able to publish on any wildcard topics.

This module uses Einar Stangvik's ws module for the WebSocket side, and Adam Rudd's mqtt.js module for the MQTT side.


The reason I wrote this was to allow browser-based clients to have access to information being published over MQTT. There are other solutions to this problem as well; for instance, there is currently a Paho Javascript client which tunnels the MQTT protocol through a WebSocket. While tunneling will certainly work (once the MQTT servers all support it), it makes the browser code more complex, and it also means that if you decide to change to a different pub/sub protocol, you then have to change all of your browser code to match. Using a bridge, you could simply change the backend pub/sub mechanism (and, of course, the bridge), and all you would have to change in your browser code would be, possibly, the URL that they connect to. This adds a great deal of flexibility in your architecture.


$ npm install mqtt-ws



Usage: mqttwsBridge

  -p, --port        MQTT port to connect to      [default: 1883]
  -h, --host        Hostname of MQTT server      [default: "localhost"]
  -l, --listen      WebSocket port to listen on  [default: 80]
  -c, --configFile  Configuration file
  --help            Show this help

Configuration File

If you specify a configuration file on the command line, it is expecting a JSON-formatted file that looks something like this:

    "mqtt": {
        "host": "mqttHost",
        "port": 1883
    "websocket": {
        "port": 8080

The mqtt section specifies the MQTT connection parameters - host and port, and the websocket section is configuration information passed to the ws module.


Logging is done via log4js. Configuration for it may be added in the configuration file under key "log4js"; see the example in the example folder. By default, everything logs to the console.


To connect to the bridge and subscribe to an MQTT topic, connect using the URL ws://host[:port]/topic[?options]. For instance, if I have the bridge running on host myHost, and port 8080, and want to subscribe to topic room1/temperature, I would use the URL ws://myHost:8080/room1/temperature. I could then publish on that topic by simply sending data over the WebSocket connection.

You can also subscribe to wildcard topics. For instance, if I wanted to listen to all topics I could connect to the URL ws://myHost:8080/%23 (Note: the # has to be URL encoded).


Receiving Messages

The websocket will receive just the message payload, unless it is subscribed to a wildcard topic, in which case it will receive the message in the form 'topic: payload'.

Publishing Messages

Messages sent over the websocket connection will be published on the MQTT topic the websocket is subscribed to, unless it is a wildcard topic, in which case the message will be handled however the MQTT server handles such messages (in most cases, it will be dropped).


In addition to a topic, you can specify MQTT options as query parameters in the URL. There are two sets of options you can specify - connection options and publishing options. Both are passed to MQTT.js whenever a connection is created or a message is published.

Connection Options

The connection options are:

  • protocolId - String protocol ID
  • protocolVersion - Integer between 0 and 255
  • clean - Set to nonzero for a clean session, zero (the default) otherwise
  • keepalive - Set to keepalive value, between 0 and 65535
  • clientId - Set to the client ID, otherwise on is generated
  • username - Set to the username for authentication
  • password - Set to the password for authentication

Publishing Options

The publishing options are:

  • qos - Quality of service value, either 0 (the default), 1 or 2
  • retain - Set to true to retain the published value on the server, false (the default) not to


For example, in the scenario above, to set up a connection subscribed to topic foobar with clientId myClient, username foo, password myPassword, and which always publishes with a QOS value of 1, use the URL:



There is an API as well, which will allow you to create your own bridge server.


MQTT/WebSocket Bridge library and binary for Node.js







No packages published


  • JavaScript 100.0%