MQTT over Websockets with HiveMQ

Written by The HiveMQ Team

Category: MQTT

Published: August 28, 2013




One of the big new features of the HiveMQ 1.4 release is definitely the native support for MQTT over Websockets. Every modern browser on any device is now a potential full-fledged MQTT client. With real publish/subscribe in the browser, web apps can take full advantage of highly scalable messaging with a very low bandwidth footprint.

Why websockets

Websockets are around for a long time now. There were many competing websocket implementations and almost every browser had its own implementation specific idiosyncrasies. Nowadays most relevant browsers support websockets. Websockets have very little overhead in terms of bandwidth and latency compared to classic HTTP requests which are needed when using (long) polling. This philosophy of having as little overhead as possible fits very well to MQTT.

With MQTT over websockets every browser can be a MQTT device. Due to the publish/subscribe pattern of MQTT, you get a real time push to your browser when an event - literally anywhere in the world - occurs, as long as you subscribe to the correct topic. With MQTT you get the following features on top of standard websocket pushes:

  • Quality of Service semantics: When using QoS 12, you get the assurance that your message arrived on the client or broker at least once/exactly once.
  • Queuing: When using QoS 1 or 2 and a persistent session, the broker will queue all messages your client misses from its subscriptions when it’s not connected. On reconnect, all messages are delivered instantly to your client.
  • Retained messages: Messages which are retained on the server are delivered when your client subscribes to one of these topics instantly.
  • Last Will and Testament: If your client doesn’t disconnect gracefully, it’s possible to publish a message to a topic to notify everyone who is interested, that your client died.
  • If your client connects to the broker with a persistent session, you don’t have to resubscribe to all the topics your client is interested to, as all previous subscriptions are stored on the server.

How do websockets and MQTT fit together?

Messages over websockets are sent in frames. These frames have only 2 byte overhead. The whole MQTT message (with all its headers and payload) is now sent with the websocket frame.

websockets

MQTT Messages in Websocket Frames

HiveMQ expects that every MQTT message is sent in exactly one websocket frame. Common Javascript MQTT libraries like Paho.js implement this behaviour.

Native Websockets

HiveMQ implements all websocket standards (including RFC6555, all hixie and all hybi drafts) natively. That means, that you don’t need a dedicated webserver in front of a HiveMQ MQTT broker instance to forward the websocket connection. HiveMQ handles the HTTP websocket upgrade and the actual websockets transparently. The broker treats a MQTT client connection over websockets as equal to connections over “plain TCP”.

Other MQTT brokers with the need for an additional web server

The following shows any MQTT broker without websockets support and how MQTT over websockets could be achieved:

Websockets with a MQTT broker and a Webserver

Websockets with a MQTT broker and a Webserver

As you can see an additional webserver is needed. Unfortunately many webservers (like Apache or lighthttpd) need specific modules or source patches if you want to forward the websocket connection to your MQTT broker. And of course you have to configure the web server properly.

HiveMQ with native websockets

In contrast, the following shows how MQTT over websockets are done with HiveMQ:

Websockets with HiveMQ - No additional webserver needed

Websockets with HiveMQ - No additional webserver needed

As you can see, a web application which utilizes websockets is a first class MQTT client for HiveMQ. No additional web servers needed, no fiddling around with obscure config files. It just works out of the box.

Configuration

For HiveMQ 2.x To enable websockets, just set the following properties in the configuration.properties file:

1
2
websockets.enabled=true
websockets.port=80  //Use any port you like

For a full list of configuration options, please refer to the official documentation.

For HiveMQ 3.x

Edit the config.xml file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="../../hivemq-config.xsd">

   <listeners>
      <websocket-listener>
          <port>8000</port>
          <bind-address>0.0.0.0</bind-address>
          <path>/mqtt</path>
          <subprotocols>
              <subprotocol>mqttv3.1</subprotocol>
              <subprotocol>mqtt</subprotocol>
          </subprotocols>
          <allow-extensions>true</allow-extensions>
      </websocket-listener>
       ...
   </listeners>
    ...
</hivemq>

You can find the complete documentation here.

Secure Websockets

For HiveMQ 2.x Secure Websockets are a great way to enable security on the transport layer. HiveMQ offers secure websockets out of the box. It’s even possible to use secure websockets and standard websockets simultaneously.

To enable secure websockets, add a valid certificate to HiveMQs keystore and set the following properties in the configuration.properties file:

1
2
websockets.secure.enabled=true
websockets.secure.port=443

For HiveMQ 3.x

Edit the config.xml file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
<tls-websocket-listener>
    <port>8000</port>
    <bind-address>0.0.0.0</bind-address>
    <path>/mqtt</path>
    <subprotocols>
        <subprotocol>mqttv3.1</subprotocol>
        <subprotocol>mqtt</subprotocol>
    </subprotocols>
    <allow-extensions>true</allow-extensions>
    <tls>
        <keystore>
            <path>/path/to/the/key/store.jks</path>
            <password>password-keystore</password>
            <private-key-password>password-key</private-key-password>
        </keystore>
        <client-authentication-mode>NONE</client-authentication-mode>
    </tls>
</tls-websocket-listener>

For a full list of configuration options, please refer to the official documentation.

Client libraries

We can recommend the following Libraries:

Conclusion

MQTT over Websockets has many advantages and enables you to write a new generation of web applications. With HiveMQ it’s dead easy to use websockets, they just work out of the box without any complicated configuration. You don’t need any additional software, you just have to enable websockets in the HiveMQ config.

We are curious what cool app you want to build with MQTT over Websockets. Drop us a line or write a comment!

About The HiveMQ Team

We love writing about MQTT, IoT protocols and architecture in general. Our experts are here to help, so reach out to us if we can help!
Contact us
<  A full-featured MQTT client for your browser   |   Supporting MQTT client identifiers with more than 23 characters   >