This post describes the steps I used to set up the Mosquitto MQTT broker (server) with websockets enabled on a Raspberry Pi .

This can provide two-way communication between Python programs and JavaScript.

For example:

A python program can send a message and have JavaScript update part of a web page in a way that is similar to AJAX.

A button on a web page can cause JavaScript to send a message telling  Python to run a function or method.

Updated March 08 2018
This post has been updated to install Mosquitto version 1.4.15

There has been a new problem with the install from the Mosquitto debian repository.
If you install from that source and get a segmentation fault error when you try to run it, you can still do the build as described in this post to ge a working install.

Updated January 15 2018
As of Jan. 14 2018 the install from the Mosquitto debian repository has been fixed and installs mosquitto on Raspbian stretch with websockets enabled without error.
You may still find the information in this post about enabling websockets in the mosquitto.conf file useful.

Updated November 29 2017
This update includes instructions for installing Mosquitto on a Raspberry Pi running Raspbian Stretch.

Installing from the Mosquitto Debian repository

There is a Debian repository with the latest Mosquito binary which has been compiled with websockets enabled out of the box.

The first few steps are for adding the Mosquitto Debian repository to your system. They are taken directly from the Mosquitto blog post and are reproduced here (with slight modifications) to keep everything in one place.

To use the new repository you should first import and install the repository package signing key.

wget http://repo.mosquitto.org/debian/mosquitto-repo.gpg.key

sudo apt-key add mosquitto-repo.gpg.key

To make the repository available to apt:

cd /etc/apt/sources.list.d/

Then do one of the following, depending on which version of raspbian you are using.

sudo wget http://repo.mosquitto.org/debian/mosquitto-wheezy.list

sudo wget http://repo.mosquitto.org/debian/mosquitto-jessie.list

sudo wget http://repo.mosquitto.org/debian/mosquitto-stretch.list

Update apt information.

sudo apt-get update

Install Mosquitto:

sudo apt-get install mosquitto

If you get an error such as:

The following packages have unmet dependencies:
mosquitto : Depends: libssl1.0.0 (>= 1.0.1) but it is not installable
Depends: libwebsockets3 (>= 1.2) but it is not installable

Then you will need to build Mosquitto from source but don’t worry it is fairly painless and because the build process on the Raspberry Pi B2 or B3 can be set to use all 4 processor cores it doesn’t take long.

The instructions which follow have been completely updated as of November 29 2017 and have been tested by building the Mosquitto MQTT broker on a Raspberry Pi running Raspbian Stretch but should also work on other Debian systems

Building from source

Prepare a fresh SD card with the latest Raspbian Stretch (optional)

If you will be accessing the Pi over ssh be sure to add a file named ssh to the root directory on the card to enable ssh.

Make any necessary changes to the password and local, time zone, etc with:

sudo raspi-config

Updtate with:

sudo apt-get update
sudo apt-get dist-upgrade

Install dependancies

sudo apt-get install cmake libssl-dev libwebsockets-dev uuid-dev libc-ares-dev

Make a temporary directory for your build files

mkdir temp

move into your new directory:

cd temp

Download and unzip the source files for c-aries

wget http://c-ares.haxx.se/download/c-ares-1.12.0.tar.gz
tar -xvf c-ares-1.12.0.tar.gz

move into the c-ares directory

cd c-ares-1.12.0

configure and build c-ares

./configure
make -j4

The -j4 switch enables building on all 4 processor cores.

Install c-ares

sudo make install

move back to the temp directory

cd ..

download and unzip the mosquitto source files

wget http://mosquitto.org/files/source/mosquitto-1.4.15.tar.gz
tar xavf mosquitto-1.4.15.tar.gz

move into the mosquitto directory

cd mosquitto-1.4.15

Run cmake with the websockets option

cmake -DWITH_WEBSOCKETS=ON .

Be sure to include the dot (.) at the end after the space

Run the build and install Mosquitto

make -j4
sudo make install

Move back to your home directory

cd ~

Optional: remove the temp directory to free space

rm -r temp

Add Mosquitto as a user:

useradd -r -m -d /var/lib/mosquitto -s /usr/sbin/nologin -g nogroup mosquitto

You should find the mosquitto executable at:

/usr/local/sbin/mosquitto

The config files should be at:

/usr/local/etc/mosquitto/

Enabling websockets

In order to enable websockets you will need to edit the Mosquitto configuration file.

If you installed mosquitto from source, the config file should be found located at:

/usr/local/etc/mosquitto/mosquitto.conf

If you installed mosquitto from the mosquitto debian repository, you should find an example config file at:

/usr/share/doc/mosquitto/examples/mosquitto.conf.gz

The mosquitto.conf file in the examples folder may be gziped you can unzipe it with:

cd /usr/share/doc/mosquitto/examples
gunzip mosquitto.conf.gz

If the files are not at the locations listed above, you can find where they are with:

whereis mosquitto

Edit mosquitto.conf

The mosquitto config file is where most of the settings that control mosquitto’s behavior, including security features, live.

It is necessary to change some settings in order for websockets to operate.

Open the mosquitto config file in your favorite text editor

sudo editor mosquitto.conf

or

sudo editor /usr/local/etc/mosquitto/mosquitto.conf

As you scroll down through the file you will see many settings. I changed the following (mostly by removing the leading # to uncomment the setting):

line ~35: pid_file /var/run/mosquitto.pid

line ~43: user mosquitto

The following settings are for the default (Python) client.

line ~133: bind_address 0.0.0.0

line ~136: port 1883

line ~151: protocol mqtt

The following settings under Extra listeners are for the JavaScript client.

line ~277: listener 9001 0.0.0.0

line ~297: protocol websockets

Optional:

If you will be using mosquitto to build a web based UI, you can have it also act as a web server for your pages.

line ~301: http_dir /usr/share/mosquitto/www

Create the directory for  the web files:

sudo mkdir -p  /usr/share/mosquitto/www

Place your HTML, CSS and Javascript files (or a symlink to them) in the www directory.

Note: If there is more that one space between a setting name and it’s value, the file won’t load.

Copy the edited config file

First backup the mosuitto.cong file provided by the inatall:

mv /etc/mosquitto/mosquitto.conf /etc/mosquitto/mosquitto.conf.bak

then

cp mosquitto.conf /etc/mosquitto/

Test your installation

mosquitto -c /etc/mosquitto/mosquitto.conf

You should see something like:

1512012962: mosquitto version 1.4.14 (build date 2017-11-29 15:51:45-0800) starting
1512012962: Config loaded from /usr/local/etc/mosquitto/mosquitto.conf.
1512012962: Opening websockets listen socket on port 9001.
1512012962: Opening ipv4 listen socket on port 1883.

Get and set up systemd unit file from GitHub

Note: If you installed mosquitto 1.4.14 with apt-get install mosquitto, a systemd unit file has already been installed.

The following instructions include the installation of a systemd unit file in place of the older init.d script which is used with Raspbian Wheezy. The older init.d script is included  with the Mosquitto installation. While the newer systemd which is used in Raspbian Jessie and Stretch is backward compatible with the init.d script, the systemd unit file is much simpler and more efficient. these steps can also be considered optional.

If you are running Raspbian light you may need to install Git. You can do so with:

sudo apt-get install git

First disable the init.d script:

sudo update-rc.d mosquitto remove

Then

sudo git clone https://github.com/Dan-in-CA/mosquitto_unit_file.git

Note: This unit file contains paths to the Mosquitto executable and config files. Please check to be sure the paths match your system and modify if necessary.

copy the mosquitto.service file

sudo cp mosquitto_unit_file/mosquitto.service /etc/systemd/system/mosquitto.service

Enable the service

sudo systemctl enable mosquitto.service

After a reboot you can use:

sudo systemctl status | stop | start | restart mosquitto

to control the mosquitto daemon. This is extremely useful when editing and testing the mosquitto.conf file.

The systemd unit file also tells mosquitto which config file to use. Otherwise the mosquitto daemon uses defalult settings which won’t work for our intended purpose. You can test mosquitto using the default settings with:

mosquitto -h

This will tell you the version of mosquitto you are running.

That’s it!

I did not set up any security or other options but it is a good idea to read through the config file to learn what is available.

Notes on usage:

Python and JavaScript MQTT client software is required and can be downloaded from the Paho project. See related post Building a browser based User Interface with MQTT

The Python client communicates with the mosquitto broker using the default MQTT protocol and port 1883.

The JavaScript client communicates with the mosquitto broker using the websockets protocol and a port such as 9001 .

A common mistake is to try and use port 9001 from Python. This will cause Python to hang without raising an exception and can be hard to debug.