2. Installation

The following steps to set up a working environment are valid for both, the Raspberry Pi and a laptop/computer. Remember, the modules can be used on a laptop/computer for remote controlling the Raspberry Pis GPIOs or on the Raspberry Pi itself without any modifications of the source code of the modules. On the Raspberry Pi, the latest Raspbian version and afterwards all available updates should be installed. The latest Raspbian image can be downladed from Raspbian Downloads [1] . Installing all available updates is described here Raspbian Update [2] .

2.1. Getting files

One option is creating a folder named 360pibot in the Raspberry Pis home folder

cd ~
mkdir 360pibot

and then connect the Raspberry Pi to the internet, open the projects github page, download the repository as a .zip file and unzip it in the created 360pibot folder.

Another option is to clone the git repository to the home folder. This will automatically create the 360pibot folder and download the project files. First, git will be installed, then the repository will be cloned.

sudo apt-get update
sudo apt-get install git
cd ~
git clone https://github.com/choeffer/360pibot

Both methods for getting the project files are also working on a laptop/computer.

2.2. Installing needed modules

Next step is to install the needed modules. They can be installed in the global Python 3 environment or in a virtual Python 3 environment. The latter has the advantage that the packages are isolated from other projects and also from the system wide installed global once. If things get messed up, the virtual environment can just be deleted and created from scratch again. For more informations about virtual environments in Python 3, see venv1 [3] and venv2 [4] . First, installing with a virtual environment will be explainend, afterwards with using the global Python 3 environment.

2.2.1. With a virtual environment

On a Raspberry Pi first ensure that the packages python3-venv and python3-pip are installed. This has also to be checked on Debian based distributions like Ubuntu/Mint.

sudo apt-get update
sudo apt-get install python3-venv python3-pip

Afterwards, navigate to the created 360pibot folder and create a virtual environment named venv and activate it. An activated virtual environment is indicated by a (venv) in the beginning of the terminal prompt.

Note

The created venv folder is added to the .gitignore file and will therefore not be tracked by git.

cd ~
cd 360pibot
python3 -m venv venv
source venv/bin/activate

With the activated virtual environment install the needed pigpio module inside.

pip3 install pigpio

Deactivating the acvtivated virtual environment can be done later by just typing deactivate in the terminal where the virtual environment is activated.

deactivate

Note

For later using the installed module, the virtual environment has to be activated, because the pigpio package is installed inside and is not callable from the global Python 3 environment.

2.2.2. Without a virtual environment

On a Raspberry Pi first ensure that the package python3-pip is installed. This has also to be checked on Debian based distributions like Ubuntu/Mint. Then, the pigpio module will be installed in the global Python 3 environment.

sudo apt-get update
sudo apt-get install python3-pip
pip3 install pigpio

2.3. Building/modifying the documentation

The whole documentation is made with Sphinx [5] and can be extended or modified as needed for e.g. documenting own projects based on this or if extending functionality of the modules and documenting this. The whole documentation is stored in the docs/ folder. The standard docstring format (ReStructuredText [11] (reST)) is used. The used theme is from Read the Docs [6] where also the documentation is hosted. Therefore, two more modules are needed for beeing able to build or extend/modify the documentation. How to use Sphinx is not part of this documentation. But there are good introductions and tutorials available which provide a good starting point, see docs1 [12] , docs2 [13] , docs3 [14] and docs4 [15] .

Note

For the creation of the docs conf.py , index.rst , and folder structure etc. the sphinx-quickstart command was used.

Note

The created docs/_build folder is added to the .gitignore file and will therefore not be tracked by git. This folder contains the output after building the docs.

If using a virtual environment to install the two modules

cd ~
cd 360pibot
source venv/bin/activate
pip3 install sphinx sphinx_rtd_theme

or if installing them in the global Python 3 environment.

pip3 install sphinx sphinx_rtd_theme

After this, the following command make html builds the html documentation which will be stored in the docs/_build/html/ folder. There, open the index.html with your preferred web browser.

If using a virtual environment

cd ~
cd 360pibot
source venv/bin/activate
cd docs
make html

or if using the global Python 3 environment.

cd ~
cd 360pibot/docs
make html

Sphinx can create the documentation in different formats (e.g. latex, html ,pdf, epub), see sphinx-build [18] for more informations.

2.4. Used module versions

The requirements.txt file will install the exact versions of the modules which are used while experimenting/developing with the demo implementation and writing the documentation.

This can be done by using a virtual environment

cd ~
cd 360pibot
source venv/bin/activate
pip3 install -r requirements.txt

or by installing them in the global Python 3 environment.

pip3 install -r requirements.txt

The requirements.txt file is created with pip3 freeze > requirements.txt. The requirements_rtd.txt file is used by Read the Docs [6] . The online version of the documentation is auto build/updated each time a git push is made to the github repository. For further information, see Read the Docs Webhooks [17] .

2.5. Raspberry Pi

The following steps are specific to the Raspberry Pi. It is necessary to install the pigpio package, enable starting the pigpio daemon at boot and then doing a reboot to activate the pigpio daemon. For more information see pigpio_download [7] and remote_pin [10] . For the demo implementation the package from the Raspbian repository is installed. This ensures that the package is good integrated in the system, even if it might be a bit older.

sudo apt-get update
sudo apt-get install pigpio
sudo systemctl enable pigpiod
sudo reboot

Note

If the Raspberry Pis GPIOs are not responding anymore, it might help to restart the pigpio daemon on the Raspberry Pi. For that, SSH into the Raspberry Pi if remotely working with it, otherwise use the local terminal, and execute the following two commands.

sudo systemctl daemon-reload
sudo systemctl restart pigpiod.service

2.5.1. Hotspot and remote access

An important step which improves programming/controlling the Raspberry Pi is to make it remotely accessible. This can be done by connecting the Raspberry Pi to a WLAN network or by enabling a hotspot on it, see pi_hotspot [8] . This is recommended before using it. Setting up a hotspot will not be covered here, because the official documentation is good and updated regularly to match the latest Raspbian changes.

Also make yourself familiar with using VNC [9] or using remote_pin [10] . Latter will again drastically improve the use of the modules, because then all programming/controlling can be done on a laptop/computer inlcuding using an IDE, having much more system ressources and so on. The latter option is shortly described.

After enabling a hotspot on the Raspberry Pi and beeing connected with your laptop/computer, the following steps are needed to remote control the Raspberry Pis GPIOs. For a more detailed description, see remote_pin [10] .

First, in the Raspberry Pi configuration Remote GPIO has to be enabled. This can be done via GUI or sudo raspi-config. This will allow remote connections while the pigpio daemon is running.

Then, the environment variable has to be set while or before launching Python 3 or an IDE. This variable will point to the IP address (and optional port) on which the Raspberry Pi is accessible. This can be on its own provided hotspot/network or on a WLAN it is connected to.

PIGPIO_ADDR=192.168.1.3 python3 hello.py
PIGPIO_ADDR=192.168.1.3 python3 code .

There are also other possibilities available for configuring remote access. They are mentioned in the pigpio documentation, see pigpio_pi [16] . E.g. the IP address and port can be passed as arguments if initializing a pigpio.pi() instance.