Using MQTT Over WebSockets with Mosquitto

What is Websockets and How it Works?

WebSocket is a computer communications protocol, providing full-duplex communication channels over a single TCP/IP connection. Wiki

It is closely associated with http as it uses http for the initial connection establishment..

The client and server connect using http and then negotiate a connection upgrade to websockets, the connection then switches from http to websockets.

The client and server can now exchange full duplex binary data over the connection.

Video -MQTT Over Websockets Explained


Why Use MQTT over Websockets?

MQTT over Websockets allows you to receive MQTT data directly into a web browser.

This is important as the web browser may become the DE-facto interface for displaying MQTT data.

MQTT websocket support for web browsers is provided by the JavaScript client.

MQTT Over Websockets vs MQTT.

In the case of MQTT over Websockets the websockets connection forms an outer pipe for the MQTT protocol.

The  MQTT broker places the MQTT packet into a websockets packet, and sends it to the client.

The client unpacks the MQTT packet from the websockets packet and then processes it as a normal MQTT packet.

This is illustrated in the diagram below:


With MQTT the MQTT Packet is placed directly into the TCP/IP Packet.

Websockets and Mosquitto

Note: This section is left for reference. Windows install packages still don’t have websockets.Linux package installed using apt-get currently installs mosquitto version 1.4.12 and has websockets support already complied in to it.

The default Mosquitto install packages for Windows and Linux do not include support for WebSockets.

If you want to test WebSockets with MQTT then you need to either:

  • Compile and install your own Mosquitto broker with Websocket support.
  • Use an oneline broker that has websocket support

There are instructions for compiling Mosquitto with websockets here (Linux) and here (windows).

Instruction Notes for

The instructions in the guide work. but I needed to make some slight changes as detailed here:

Couldn’t find libwebsockets-1.22-chrome26-firefox18.tar.gz so I used this instead libwebsocckets-1.7.8.tar.gz. Got it from here

There was no makefile so I had to create the build directory and run cmake.

The ares.h file was missing, so I needed to install it as per instructions.

I kept forgetting to run commands as sudo which meant copies failed when running make.

When I started the broker it couldn’t find but running the command

sudo ldconfig

solved it.

Websockets on Windows

Since mosquitto 1.5.1 websockets support has been enabled on the windows binary files.

However when you start mosquitto it appears to be listening on the websocket port but doesn’t allow connections.

mosquitto v 1.5.4 does work with websockets. Here is a link for the downloads.

Configuring Websockets On Your Own Mosquitto Broker

MQTT over Websockets usually uses port 9001 but it isn’t fixed.

You need to make change to the mosquitto.conf file, by adding the following:

listener 9001
protocol websockets

This creates an extra listener using websockets and port 9001.

When you start the broker you should see something like this:


Testing Websockets

To test websockets you will need a client that supports websockets.

Here we look a using both the paho python client and the paho Javascript client.

Websockets and the Python Client -Example

To tell the client to use websockets instead of MQTT use the command

client= paho.Client(“control1”,transport=’websockets’)

instead of simply

client= paho.Client(“control1”)

When creating a new MQTT client object.

You also need to set the port to the WebSocket port. (9001).

Here is a Python demo script that you can use to publish and subscribe using websockets.

If you run the script you see:


There is no real indication that the client is using websockets as opposed to standard MQTT.

JavaScript Web Browser Client

The client is meant to be run in a browser and so you need to create a web page and add your JavaScript code.

See this tutorial- Understanding and using The JavaScript MQTT Client With Websockets for detailed usage examples, scripts and download links.

Here is a link to the MQTT websockets Javascript docs


Using Websockets over TLS (SSL)

To use websockets over TLS you need to configure the broker to use TLS.

See this tutorial Mosquitto SSL Configuration -MQTT TLS Security.

Now we edit our mosquitto.conf file. It should look like this:websockets-ssl-config-mosquitto

Notice The extra listener is using websockets and the ssl configuration applies to it. I also used port 8081.

On the Python client add the client.tls_set() command to tell it to use SSL as well as setting the transport.:

client= paho.Client("control1",transport='websockets')


Using an External MQTT Broker with Websockets

If you can’t get websockets on your own broker then you can use as external one like :

  •– uses port 8080 un-encrypted and 8081 for websockets over SSL.
  • support only encrypted and uses port 443 for websockets over SSL..
  • -uses port 8000 for websockets. Websockets over SSL not supported.

Here is a list of other test brokers with Port numbers

Common Questions and Answers

Q- Can You use websockets over an encrypted connection?

A- Yes

Q- Are there two JavaScript Clients?

A- Yes the one uses MQTT over Websockets and is meant to be run in a browser. The other uses MQTT and is meant for use with node.js.See Using the Node.js MQTT Client-Starting Guide

Related Tutorials and resources

Please rate? And use Comments to let me know more
[Total: 7    Average: 3.6/5]


  1. Hi Steve.
    I am trying a secure connection through websockets and TCP ,using self signed certificates at both client and server side. I am able to connect through TCP using certificates but fail on websockets.
    Although, it works fine without certificates on websockets.
    My mosquitto config file looks like this(running on Ubuntu) :

    port 8885
    log_type error
    log_type notice
    log_type information
    log_type debug
    cafile C:/Program Files/mosquitto/ca.crt
    keyfile C:/Program Files/mosquitto/server.key
    certfile C:/Program Files/mosquitto/server.crt
    require_certificate true
    use_identity_as_username true

    listener 9001
    protocol websockets
    cafile C:/Program Files/mosquitto/ca.crt
    keyfile C:/Program Files/mosquitto/server.key
    certfile C:/Program Files/mosquitto/server.crt
    require_certificate true
    http_dir C:/Program Files/abc

    I am trying to connect through c#(.net) client using MQTTnet dll which is running on Windows machine.
    Below is the c# code of my client :

    options = new ManagedMqttClientOptionsBuilder()
    .WithClientOptions(new MqttClientOptionsBuilder()
    .WithTls(new MqttClientOptionsBuilderTlsParameters()
    SslProtocol = System.Security.Authentication.SslProtocols.Default,
    AllowUntrustedCertificates = true,

    UseTls = true,
    Certificates = new List { new X509Certificate2(certificate).Export(X509ContentType.Cert) },
    CertificateValidationCallback = delegate { return true; },
    IgnoreCertificateChainErrors = true,
    IgnoreCertificateRevocationErrors = true
    var client = _mqttFactory.CreateManagedMqttClient();
    var message = new MqttApplicationMessageBuilder()
    .WithPayload(this.msgTxt.Text + DateTime.Now.ToString())
    var result = client.StartAsync(options);

    I am able to connect through Paho client on websockets with and without using certificates. But somehow, it fails if i am using .net client.

    1. If it works with the paho Python client then it can’t be a broker issue so it is something in the .net. Unfortunately I’ve never worked with .net so can’t be of much help there.

  2. Hi Steve,

    thanks for the tutorial.

    Can I publish a websocket request via http url?

    How would that look like?

    Thanks T

    1. Websockets uses http as part of the initial connection setup and hence it uses the url.
      If you take a look at the Javascript example you will see this

  3. Hi Steve
    i did consider that (for a few seconds) the nodes are at two different locations all doing the same thing. the common point is hiveMq so what you are saying is logical. i had ruled it out because i did not realise that they were unreliable.
    thanks for the reply, it has given me more confidence in my nodes and perhaps less in hiveMq

  4. hi Steve
    you helped me once before and everything has been working well until recently 🙂
    now however i have run into a problem which is outside my experience.
    using hiveMq with 5 esp nodes connected i suddenly stopped receiving posted messages.
    this can go on for a few days, then just as unexpectedly they start again, sometimes just a few before the next block, then another long wait.
    i have tried changing user id and topics but it has no effect. nodes always connect as does my monitor web page (which also does not receive topics)
    it is almost as though something is filling up and then stopping.
    all messages are quos 0 and none are retained
    is this something you have had experience of in the past
    thank you for your thoughts
    Dave Jelfs

    1. Dave
      Are you sure it isn’t the broker going down?
      The free providers are not very reliable. I’ve experienced many problems with them.

  5. Hi Steve,

    I was wondering if you can help me. I have installed Mosquitto successfully in the past but for some reason stuck on a new build. Mosquitto installs correct with both MQTT and Websocket listening on 1883 and 1884 respectively. I can connect to the ports fine, however the publish messages isn’t showing up on Websocket connection. Any ideas?

    Thank you in advance.


    1. If you are on windows download the files from the site and use the mosquitto.exe file from the download files as it is an older version that works.
      I had someone the other week with a problem with SSL over websockets and it was because they had a new version of Mosquitto. Sorry but can’t remember which version.

      Note: Problem solved by going back to 1.4.15

  6. Hi Again Steve
    thanks for the quick reply (and link)
    all works fine with hivemq, great stuff
    thanks for your support

  7. hi Steve
    thanks for the article, it is most informative
    i am using mqttws31 and trying to connect to with connection string
    ‘ws://’ but get back connection refused
    could you post a link to the html mentioned about please, this might help me to get the connection established

  8. Hi Steve
    I,m trying to install MQTT in raspberry pi 3 and im getting the below error at the end.
    What the cause?

    Reading package lists… Done
    Building dependency tree
    Reading state information… Done
    Some packages could not be installed. This may mean that you have
    requested an impossible situation or if you are using the unstable
    distribution that some required packages have not yet been created
    or been moved out of Incoming.
    The following information may help to resolve the situation:

    The following packages have unmet dependencies:
    mosquitto : Depends: libssl1.0.0 (>= 1.0.0) but it is not installable
    Depends: libwebsockets3 (>= 1.2) but it is not installable
    N: Ignoring file ‘mosquitto-jessie.list.1’ in directory ‘/etc/apt/sources.list.d/’ as it has an invalid filename extension
    N: Ignoring file ‘mosquitto-jessie.list.2’ in directory ‘/etc/apt/sources.list.d/’ as it has an invalid filename extension
    E: Unable to correct problems, you have held broken packages.

  9. Just a question
    may I manage on a single istance of Mosquitto server both MQTT and WebSoket protocol so connet either a ordinary MQTT client and a browser ?

    is this the corret mosquitto.conf configuration ?

    port 1883
    protocol mqtt
    listener 9001
    protocol websockets

  10. Excellent Post on Mosquitto Broker, Client, Websocket and Javascript. I am currently working on MQTT and looking a head on using MQTT for web communicaiton. So, your post will definitely come in handy. Thank you so much Steve.

  11. Hi,

    Please disregard the my last comment.
    I found that the version of libssl I had was incompatible with the libwebsockets version we are using.
    I reverted the changes I made to ssl.c. I removed libssl-dev and installed libssl1.0-dev using apt-get.
    Then I did a clean build of both libwebsockets and mosquitto. Both built without error.


  12. Hi Leechads,

    I encountered the same problem.

    If you just comment out the two offending lines in /c/libwebsockets-1.4-chrome43-firefox-36/lib/ssl.c it should build ok.

    The function call causing the error has been deprecated. It does nothing and can safely be removed.


  13. right now i am try to install using compile method on raspberry pi but i am getting the following error on the cmake stage:

    pi@raspberrypi:/c/libwebsockets-1.4-chrome43-firefox-36/build $ sudo cmake -DLWS_IPV6=OFF ..
    — The C compiler identification is GNU 6.3.0
    — Check for working C compiler: /usr/bin/cc
    — Check for working C compiler: /usr/bin/cc — works
    — Detecting C compiler ABI info
    — Detecting C compiler ABI info – done
    — Detecting C compile features
    — Detecting C compile features – done
    — Found Git: /usr/bin/git
    fatal: Not a git repository (or any of the parent directories): .git
    Git commit hash:
    — Performing Test HAVE_inline
    — Performing Test HAVE_inline – Failed
    — Performing Test HAVE___inline__
    — Performing Test HAVE___inline__ – Failed
    — Performing Test HAVE___inline
    — Performing Test HAVE___inline – Failed
    — Looking for bzero
    — Looking for bzero – found

    Comment truncated

    1. Sorry but I’m not an expert on compiling c files. I have only done it once recently and that was to get websockets working. I had to take each error message and resolve it by doing an internet search. It seems like yours failed early with git I would try and resolve that first and work your way through it.

    1. I assume you mean without having to compile it. As far a I know there isn’t a package available with websockets that you can install via the package manager. I would assume that if you got a copy of the binary it would complain about missing files. I can send you the binary for you to try.If I get a chance I will setup another Linux box and try it myself.

  14. thank you but i get this error when i run the code
    “Uncaught TypeError: Paho.MQTT.client is not a constructor
    at MQTTconnect ”
    i tried to solve the problem but nathing arrived. !!!

  15. Thank you for the whole information, i also develop a sytem which has multiplatform works on android, web, windows desktop. Each platform uses mqtt and works greate, for sample usage i added to my website , so you can see the efficiency of system, when you write message from this site , i will be answer from my android phone. Thanks again.

  16. I am getting a error while generating the Visual Studio project solution for libwebsockets-1.7.9
    it says :
    The C compiler identification is unknown
    CMake Error at CMakeLists.txt:7 (project):
    No CMAKE_C_COMPILER could be found.
    Please help me , how can i fix it..?

    1. You will need to use the Javascript client.
      I played around with this when I was looking at web sockets. If you want I can upload a working html page that does basic connect,publish and subscribe that you can use a a start. It will probably take a few days to sort it out. Just let me know.

      1. Ohhh Thanks Steve
        you can upload a working html page that does basic connect, publish, subscribe etc
        yes it can help us

      2. Hi Steve,
        I’m doing the same thing as you mentioned above for connecting to mqtt from browser. But I’m getting “mqttws31.js:977 WebSocket connection to ‘wss://brokerlink/’ failed: Error during WebSocket handshake: Unexpected response code: 502”. But it works in incognito mode or when I clear the cache. There is no error in log files also. I’m not getting what might be issue.

Leave a Reply

Your email address will not be published. Required fields are marked *