This is a cheatsheet to setup Freeboard on a Raspberry Pi.

Notes on MQTT

The Paho library used by the Freeboard MQTT plug-in supports MQTT over websockets. If you're using the Mosquitto MQTT broker make sure websockets have been enabled. There's a good description here. I added the following to lines to the end of my /etc/mosquitto/mosquitto.conf file to enable MQTT websockets on port 1884:

listener 1884
protocol websockets

Then restart Mosquitto:

systemctl restart mosquitto.service

Install Latest Node

sudo apt remove nodejs # to remove old version of node if installed
curl -sL https://deb.nodesource.com/setup_7.x | sudo -E bash -
sudo apt install -y nodejs
node -v

Install git, Grunt & Freeboard

sudo apt install git
git clone https://github.com/Freeboard/freeboard.git
cd freeboard
sudo npm install -g grunt-cli
npm install
grunt

Configure with Lighttpd

If you're already running Lighttpd the default directory is typically /var/www. You can move the freeboard directory to /var/www, change the owner to www-data and you should be able to browse to http://localhost/freeboard.

Configure with Apache

Assuming freeboard is installed in /home/pi, serve freeboard via Apache:

sudo ln -s /home/pi/freeboard /var/www/freeboard

Create `/etc/apache2/sites-available/freeboard.conf`:

<VirtualHost *:80>
  ServerAdmin greg@test.org
  ServerName test.org
  ServerAlias www.test.org

  DocumentRoot /var/www/freeboard
  ErrorLog ${APACHE_LOG_DIR}/error.log
  CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Enable the site

sudo a2ensite freeboard
sudo service apache2 reload

Test Freeboard

You should now find Freeboard in your browser at:

http://localhost/freeboard

Sending Test MQTT Data over Websockets

Normally, I've used the mosquitto command line tools to test publish and subscribe to MQTT data but the command line tools don't yet support Websockets so I'm going to install the node mqtt command line tool via npm on one of my systems:

sudo npm -g mqtt

Let's start by subscribing to MQTT for a broker and leave this running:

mqtt sub -h mybroker -t watchmen/bmoor/BGC/serviceOk -v -p 8883

Here's an example of publishing test data using MQTT over websockets:

mqtt pub -h mybroker -t watchmen/bmoor/BGC/serviceOk -m 544 -c testClient -p 1884 -C ws

And publishing without websockets:

mqtt pub -h mybroker -t watchmen/bmoor/BGC/serviceOk -m 544 -c testClient -p 8883

 

Next, we configure the MQTT Plug-in

Freeboard MQTT Plug-in

To setup the Freeboard MQTT Plug-In you first need to install the Paho Javascript library from here. I'm going to change to the root freeboard directory and download the library with this command:

wget https://raw.githubusercontent.com/eclipse/paho.mqtt.javascript/master/src/mqttws31.js

Switch to the freeboard plug-in directory and clone the Freeboard MQTT Plug-in with git:

cd freeboard/plugins/thirdparty
wget https://raw.githubusercontent.com/alsm/freeboard-mqtt/master/ibm.iotfoundation.plugin.js
wget https://raw.githubusercontent.com/alsm/freeboard-mqtt/master/paho.mqtt.plugin.js

Edit the ibm.iotfoundation.plugin.js file and the pahoo.mqtt.plug.js file and replace the full path to the Paho library in the references to Paho that you find in the files. In my case the full path is:

/var/www/freeboard/mqttws31.js

Edit the Freeboard index.html and load the two plug-in Javascript files:

<script type="text/javascript">
    head.js("js/freeboard+plugins.min.js",
            "plugins/thirdparty/ibm.iotfoundation.plugin.js",
            "plugins/thirdparty/paho.mqtt.plugin.js",
     // *** Load more plugins here ***
     function(){
         $(function()
            { //DOM Ready
               freeboard.initialize(true);
            });
     });
</script>

Add MQTT Source

Re-load Freeboard in the browser and click Add. Select the Paho MQTT Client and enter the rest of the parameters for your MQTT metric.

Now click Add Pane to add the widget. I'm going to add a Gauge and then immediately below it a Sparkline widget to graph the same value.

If you send some test data, you should see the gauge updated:

Saving Your Dashboard

I found saving and then displaying my dashboard to be not so obvious so here are the steps.

To save a dashboard layout, click the Save Freeboard button and then click the Pretty or Minified text that comes up. This should download a json file.

Displaying a Saved Dashboard

Now copy the downloaded json file to the root directory of your freeboard server and use the following URL format to view your dashboard:

http://localhost/freeboard/?load=seattle.json

---