Quick Start
The quickest and easiest way to install CheesePi is through the Python package management system PyPi. First, ensure you have the basic system tools installed, on a RaspberryPi use:
$ sudo apt-get install python-pip build-essential python-dev httping mtr iperf libav-tools
Then install the CheesePi module (and all its required python modules):
$ sudo pip install --upgrade cheesepi[extra]
CheesePi is made of three services (storage, dispatcher and dashboard), all can started by:
$ sudo cheesepi start all
You are now measuring your connection, results will appear in the dashboard at http://PROBE_IP:8080/.
More detailed install instructions are outlined below, configuration details are on another page.
Install directly through OS Image
Alternatively, for a fully functioning OS (either Raspbian or ODroid Ubuntu) with CheesePi already installed and configured in it then download our latest image:
- CheesePi Raspbian OS Image – CheesePi-Raspbian-latest.img.zip
- CheesePi ODroid OS Image – CheesePi-ODroid-latest.img.zip
With the bootable image download, simply follow the Raspbian image install instructions. Our image is around 4GB in size, but if you install on a larger SD card this file system can be expanded through the “Expand Filesystem” command, such as with raspi-config‘s .
The Raspbian user is called “pi” with a default password of “cheesepipass“. The ODroid user is called “odroid” with a default password of “odroid“.
Detailed Manual Install Procedure
First install suggested system packages that will enable extra CheesePi functionality, the process will differ depending on your OS type:
- Debian-like Linux:
$ sudo apt-get install python-pip build-essential python-dev httping mtr iperf libav-tools - Redhat-like Linux:
$ sudo yum install gcc python-devel httping mtr iperf libav-tools - Mac OSX:
$ sudo brew install python httping mtr iperf
If you are not on RaspberryPi (or at least ARM system) then you must also install the InfluxDB storage program. The CheesePi distribution includes an InfluxDB binary for ARM devices.
It can be simplest to install CheesePi system-wide as the root user. If you have installed the python development package (python-dev) and compilation tools for your system then you can install CheesePi with all extras (e.g. Twisted):
$ sudo pip install --upgrade cheesepi[extra]
If you can not install the extras the following will install the basic CheesePi version:
$ sudo pip install --upgrade cheesepi
It will then need to be run as root to enable automatic code upgrades. Alternatively, it can useful to use virtualenv (and so enable CheesePi to be run as a normal user):
$ sudo pip install virtualenv # install virtualenv
$ virtualenv cheesepi # make a cheesepi environment
$ source cheesepi/bin/activate # activate this virtual environment
$ pip install cheesepi # install the code in this environment
InfluxDB
CheesePi currently uses InfluxDB version 0.8 as the storage engine, due to the Grafana dashboard. If you are on an ARM based system (such as the Raspberry Pi) the ARM-binary InfluxDB distributed with the python module will work. On different system types (e.g. i386) you can install Influx 0.8 through the OS package distribution system. For example:
- Yum:
$ yum install influxdb - apt:
$ apt-get install influxdb - Brew:
$ brew install influxdb08
To use the default database storage area, just make the following directory:
$ sudo mkdir /var/lib/influxdb && sudo chown $USER /var/lib/influxdb
If you would like to store the data elsewhere, modify the paths in the config file at: ~/.influxconfig.toml
Enhanced executable permissions
Some Linux distributions require elevated permissions to run certain programs. To solve this limitation, the following commands can help:
$ sudo chmod u+s `which ping`
$ sudo chmod u+s `which iwlist`
$ sudo chmod u+s `which mtr`
Start Monitoring
To start the three component services (storage, dispatcher and dashboard), simply run:
$ cheesepi start all
Each server can be run separately (dashboard is optional):
$ cheesepi start storage
$ cheesepi start dispatcher
$ cheesepi start dashboard
If you installed as root and then started CheesePi as a normal user it will not automatically update (through a pip install --upgrade). Use virtualenv to get around this problem.
Your monitoring dashboard can then be viewed on your local network at the address printed by the install script, it will be in the form:
http://PROBE_IP:8080/ (substituting your Pi’s IP address into the URL)
You can bookmark this web page on all the computers in your home network and then you can check the (current and historical) status of your Internet connection whenever you want. If network assigns dynamic IP addresses then you probably want to set a static one for your Pi so it will always be accessible in the same place.
Start on boot
There are many differing possibilities to have CheesePi start on boot.
- On most Linux systems add the following line to your /etc/rc.local (before the last line’s exit 0):
$ cheesepi start all - Also on Linux, systemd is a more modern system for managing run-levels. We provide an LSB file in [CheesePiDir]/bin/cheesepi.service. Short instructions would be:
$ sudo cp [CheesePiDir]/bin/cheesepi.service /lib/systemd/system/
$ sudo systemctl daemon-reload
$ sudo systemctl start cheesepi.service
$ sudo systemctl enable cheesepi.service
Wifi capability
Extra steps may be required to obtain Wifi environment information, depending on the Wifi hardware dongle that you are using. Unfortunately we can not help with this step as it will be unique to all users. First try installing firmware for your wifi dongle:
$ sudo apt-get install firmware-linux-free
FAQ / Errors
- To install the system with absolutely no root permission, it is first useful to install virtualenv for the user.
- Python.h: No such file or directory – You do not have the development python package installed, so can not compile software for some of the python module CheesePi uses. This can be solved by installing the extra packages for your OS
- Tried to make the directory, but it failed: ‘module’ object has no attribute ‘mkdirs’ – You have an old version of python, simply make the directory yourself
- Problem executing influxdb command … – Install a system version of InfluxDB e.g.: sudo apt-get install influxdb
- Problem executing influxdb command … No such file or directory – On ODroid this problem can be caused by a non-standard location of ld-linux.so.3. This can be resolved adding a symlink to help locating it:
$ sudo ln -s /lib/arm-linux-gnueabihf/ld-linux.so.3 /lib/ld-linux.so.3 - Warning: Default InfluxDB storage dir /var/lib/influxdb does not exist – You have not either made the InfluxDB storage directory, or alternatively, set an different storage directory in the Influx config file ~/.influxconfig.toml.