RPi-Monitor: Advance usage and customization

Note: A new version of RPi-Monitor is available.

For all details about RPi-Monitor refer to RPi-Monitor Documentation.

Note: Information bellow are outdated



Note: A new version of RPi-Monitor is available: Version 2.0.
All the details about the latest version of Rpi-Monitor are in RPi-Monitor overview

This article as been replaced by: RPi-Monitor: Version 2.0 advance usage and customization

RPi-Monitor is designed to be flexible and configurable. But how should I do if I want to:

• Customize RPi-Monitor to fit a particular needs?
• Use it with my own Web Server? 
• Add "friends" linking RPi-Monitor running on different platform together?
• Use it into another Linux distribution than Raspbian? 
• Add other graphs from additional sources (other mount point or external temperature probe)?
• Customize graph to display bandwidth (from an idea from tduval shared in Github issue)

Photo from Flickr  cc-by-nc-nd by WingedWolf

All these questions will be answered into this post and as a bonus, we will also see how to install a little electronic DS18B20 temperature probe.

Customize RPi-Monitor to fit a particular needs

If you want to customize RPi-Monitor in a way not described bellow you just have to know 2 things:

• The man page is explaining how to use rpimonitord.
• The configuration file is documented to let you customize to your need.

You will find bellow some example of customization.

Warning: Be sure to use Linux filefeed format with line ending with LF (and not CR/LF like in Windows).

Use it with my own Web Server

In this example I will use nginx server. You could use the same tactic with your preferred web server.

Let's first update the configuration file to disable the embedded web server. Edit the file /etc/rpimonitord.conf and set noserver=1.

Then restart RPi-Monitor with the command:
    sudo service rpimonitor restart

The embedded server is no more running so, we will need to configure another server to access the data.

For nginx we will create the file /etc/nginx/sites-enabled/rpimonitor with the following content:
    server {
        listen  80;
        index   index.html;
        root    /usr/share/rpimonitor/web;
    }

and restart the server with the command:

    sudo service nginx restart

Now you can reach RPi-Monitor with your favorite browser on your favorite web server.

Add "friends" linking RPi-Monitor running on different platform together

Friends is a notion that comes in version 1.2. A friend is simply another computer running RPi-Monitor. Configuring friends will add a drop down list on the right of the top menu with a links to RPi-Monitor sitting on the other computer.

Friends menu is visible on the top right

In /etc/rpimonitord.conf, Comment starting by #> are specific comments. These comments  will be processed by rpimonitord and integrated into the json sent to the server in the form of an array having the name specified into the section. The data are not processed by rpimonitord. The server will parse and use them.

Here is an example of configuration for 3 friends:
    #>[friends]
    #>"192.168.0.123:8888=Raspberry Pi"
    #>"192.168.0.2:8888=Shuttle"
    #>"127.0.0.1:8888=Laptop"

Use it into another Linux distribution than Raspbian

RPi-Monitor has been designed to run into a Raspberry Pi but as it is using only standard Linux resources, it is not hardware dependent. A simple configuration update can make it run on Ubuntu, CentOS or any other distribution.

Ubuntu is a Debian based distribution as Raspbian. The installation can then be done using the deb package available for each releases. Download and install the package as described in this previous post.

With CentOS and withe any non Debian based distribution it will required to perform a manual installation.
After installing the perl dependencies: HTTP::Daemon (perl-libwww-perl) and RRD (rrdtool-perl), download the archive from github using the following command:
    wget http://goo.gl/5vbYu -O Version-1.5.zip

Then unpack it.
    unzip Version-1.5.zip

Finally install rpimonitor manually:
    su -
    mv RPi-Monitor-Version-1.5/rpimonitor /usr/local

You can now start RPi-Monitor with the following commands:
    cd /usr/local/rpimonitor
    ./rpimonitird

Note: I will not describe here how to configure the auto startup since each distribution has its own way to do so. An upstart script is available into RPi-Monitor github tools directory, it may help you in such an action.

Once the installation is done you can start RPi-Monitor and connect to it with your favorite browser.
You may notice that some values are not presents or displayed as NaN (Not a Number). To fix these issues, you will have to update the configuration file (/etc/rpimonitord.conf or /usr/local/rpimonitor/rpimonitor.conf).
The current version is not fully customization through the configuration file. It could then be required for experts to dive into the code to customize the pages. Javascripts doing the rendering are available in the sub directory js. Improvement are planned for version 2.0.

RPi-Monitor running on Ubuntu (before custimization)

Add other graphs from additional sources: other mount point

Lets start with something simple and see how to add graphs for additional mount point.

To add a graph to RPi-Monitor statistic, we need to create a new section. Let's call it [ExternalHDD].
Then we have to declare the new data names HDD_Free, we will get that with the command df associated with the correct regular expression. To defined the exact command, it is advised to test the command before adding it into the configuration file. This can be done easily like this:

    COMMAND | perl -ne '/REGEXP/' and print "$1\n"'

Where COMMAND will give the source of information to process and REGEXP will extract the information for RPi-Monitor. Let get an example with the command df:

pi@raspberrypi ~ $ df -t ext3
Filesystem           1K-blocks      Used Available Use% Mounted on
/dev/sdb1            140340132    192128 133019124   1% /media/storage

pi@raspberrypi ~ $ df -t ext3| perl -ne '/sdb1(?:\s+\d+){2}\s+(\d+)/ and print "$1\n"'
133019124

The command to execute is df -t ext3 and the regular expression to apply is  sdb1(?:\s+\d+){2}\s+(\d+). Note: I'll note explain regular expression here, there are many site on the Internet about this subject.
The configuration line will then be:
    HDD_FREE=df -t ext3=sdb1(?:\s+\d+){2}\s+(\d+)

To have a new graph into statistic we will add the following configuration at the end to /etc/rpimonitord.conf:
    [ExternalHDD]
    HDD_FREE=df -t ext3=sdb1(?:\s+\d+){2}\s+(\d+)

To complete the installation we have to restart RPi-Monitor and refresh the statistics page into our browser.
    sudo  service rpimonitor restart

Graph of External HDD

Add other graphs from additional sources: external temperature probe

Let's build a little electronic device to measure the room temperature and add this in the temperature graph.
Do do that, you will need:

• 1 x DS18B20
• 1 x 4.7k resistor

Plug them as described in the following schema extracted from Adafruit Lesson 11:

Lets first load the kernel module required to get the information from this probe:
    sudo modprobe gpio
    sudo modprobe w1-gpio

    sudo modprobe w1-therm

First we have to identify the id of our probe:
    ls /sys/bus/w1/devices/
    28-000004fe1847  w1_bus_master1

the id is: 28-000004fe1847. Let's now check if we can get the temperature:
    cat /sys/bus/w1/devices/28-000004fe1847/w1_slave
    5a 01 4b 46 7f ff 06 10 a3 : crc=a3 YES
    5a 01 4b 46 7f ff 06 10 a3 t=21625

It looks to work. So now we need to extract the the numbers ending the second line (21625). The regular expression will then be t.(\d+)$. I'll not do a course about what a regexp is there are many site on the internet explaining it.

Note: In version 1.x of RPi-Monitor it is prohibited to use = in regular expression.

To add a graph to RPi-Monitor statistic, we need to create a new section. Let's call it [room_temperature]. Then we have to declare the new data name room_temp, its source /sys/bus/w1/devices/28-000004fe1847/w1_slave and the associated regular expression t.(\d+)$. The line to append will look like that:
    # Room temperature
    [room_temperature]
    room_temp=/sys/bus/w1/devices/28-000004fe1847/w1_slave=t.(\d+)$

Restart RPi-Monitor with the following command and it is done:

    sudo  service rpimonitor restart

A new graph is available in statistics (wait a little bit to have data and drawing):

Use zoom feature to see the freshly added data.

If you want to add a curve into the Temperature graph, it is possible by adding the KPI line into the section [temperature] as describe bellow:
    [temperature]
    soc_temp=/sys/devices/virtual/thermal/thermal_zone0/temp=(.*)
    home_temp=/sys/bus/w1/devices/28-000004fe1847/w1_slave=t.(\d+)$

It will then be required to delete the associated rrd file:
    sudo rm /usr/share/rpimonitor/web/stat/temperature.rrd

Restarting RPi-Monitor will regenerate this file with the two describes temperature. After waiting some time to let data to be added, you will have a graph with two temperatures as in the screenshot bellow:

soc_temp and home_temp drawn on the same graph

Customize graph to display bandwidth

Some users (only one for the moment) have already share customization made like tduval who wrote the following in Github issue.

    I made a custom script to add Network Traffic Statistics.
    Here is the script shell : http://pastebin.com/XPnQN0J5
    and in the /etc/rpimonitord.conf, I add this at the end of the file:

    # Network Traffic
    [networktraffic]
    net_in=sh /usr/share/rpimonitor/web/custom/netTraffic.sh=rx.(.*)
    net_out=sh /usr/share/rpimonitor/web/custom/netTraffic.sh=tx.(.*)

   After a service rpimonitor restart, I've got this: http://hpics.li/de06f90

Bandwidth generated with the script netTraffic.sh

Thanks to him for sharing this customization.