TerraPi is a simple program that collects data from various sensors, and is able to control devices based on measurements. I wrote it to monitor and control heat, light and humidity in my pancake tortoises enclosure with a Raspberry Pi Zero.

My initial goal was to to create something that is

• a simple daemon without a hardwired GUI or web interface.
• configurable from a text file.
• easily extendable with new sensors, etc.

WARNING: Please note that this is by no means "production ready"! I am using it to control my enclosure, but it's still experimental.

The core of the program is a scheduler that fires up each Sensor Device at configurable periods. Measurements from these devices are stored in a database. This is all handled by the SensorDevice abtract class, so Sensor Device implementations only need to subclass it, and override the _measure abstract method.

It is important that one Sensor Device can have multiple sensors. For example, the BME280 is a temperature, humidity and barometric pressure sensor in one chip. These sensors are handled individually in the database (e.g. for each configured BME280 device there will be 3 sensors in the database).

Sensor Devices have a list of callbacks, so Controlled Devices can register themselves to get notified of measurements. For example, a thermostat device can register itself to a temperature sensor, and receive the temperature in its callback function every time the sensor is read.

TerraPi is a Python program so you are going to need Python, obviously. I wrote it for Python 3, and it was not tested with Python 2.

To install the program you need to get the repo, and run setup.py:

pi@raspberrypi:~ $ git clone https://github.com/sghctoma/terrapi
pi@raspberrypi:~ $ cd terrapi
pi@raspberrypi:~ $ python3 setup.py install

This will install all dependencies, and create two scripts:

• terrapi: the main program
• terrapi-dashboard: a web dashboard to show interactive measurement diagrams. This script is completely decoupled from the TerraPi daemon, it just uses the same database. The databse connection string is read from the TerraPi configuration.

You can opt-out of installing the latter by using the --without-dashboard switch:

pi@raspberrypi:~ $ python3 setup.py install --without-dashboard

You can run TerraPi right after installing, but the provided sample configuration only spits random values into the database, and uses a dummy switch for a thermostat and a light that only logs status changes. You will learn how to set up your sensors and other devices in the Configuration section.

TerraPi uses a local SQLite database by default, but you can use any database servers supported by SQLAlchemy. In order to do so, you have to set up a database for TerraPi. Here is how you can do it with PostgreSQL:

pi@raspberrypi:~ $ su - postgres
postgres@raspberrypi:~$ createdb terrapidb
postgres@raspberrypi:~$ createuser terrapiusr
postgres@raspberrypi:~$ psql
psql (9.6.7)
Type "help" for help.

postgres=# alter user terrapiusr with encrypted password 'terrapi';
ALTER ROLE
postgres=# grant all privileges on database terrapidb to terrapiusr;
GRANT
postgres=#

If you want to use the Energenie USB power switches, and don't want to run TerraPi as root (which I strongly suggest), you are going to need to install the udev (for Linux) or devd (for FreeBSD) rules, and create the sispmctl group. The install_rules setup command does this for you:

pi@raspberrypi:~ $ sudo python3 setup.py install_rules

After this you will still need to add the user you plan to run TerraPi with to the sispmctl group. On Linux:

pi@raspberrypi:~ $ sudo usermod -a -G sispmctl terrapi

And on FreeBSD:

pi@raspberrypi:~ $ sudo pw groupmod sispmctl -m terrapi

Configuration is done in a YAML file that has four main sections:

• global: Settings used by multiple devices go here. Currently only the database connection string is in the global scope.
• sensor_devices: A list of Sensor Device configurations
• controlled_devices: A list of Controlled Device configurations
• logging: Logging configuration. Please refer to the Configuration dictionary schema in the Python documentation for a complete reference.

TerraPi tries to find the configuration in the following places and order:

1. The first command line argument.
2. A file named .terrapi.yaml under the current user's home directory.
3. A file named .config/terrapi/config.yaml under the current user's home directory.
4. The file named conf/config-sample.yaml under the package directory of TerraPi.

These files are not used in an incremental fashion, the first one found is the configuration. The provided config-sample.conf file gives an example of how the configuration file should look like, but it does nothing meaningful.

The following tables describe the settings for all available devices. Settings in bold are required, the others are optional.

BME280 is a temperature, humidity and barometric pressure sensor. It supports both SPI and I2C interfaces, but TerraPi currently supports only I2C (SPI is used for the MPC3008 ADC).

DHT11, DHT22, and AMR2302 are temperature and humidity sensors. These devices use one GPIO to communicate.

This device uses one GPIO to control some other devices probably via a relay board.

This device uses an Energenie EG-PMS or EG-PM2 USB programmable power switch to control some other devices (e.g. lamps, heaters, etc.). You can have as many of these power switches as free USB ports you have. The individual devices are identified by an index or an ID, and the sockets are identified by the port number.

This Controlled Device is used to switch lights on and off, but can be used for anything that needs an on and off schedule. I control a modified ZooMed UVB/LED Terrarium Hood with this.

This Controlled Device acts as a thermostat (switches things on and off based on temperature.

There are a lot of things I want to do with this tool. Just to name a few:

• I would like to store device state switches, so that I know when a controlled device is on and off. This could be useful for e.g. a thermostat.
• Controller Devices probably should get their own main section in the future, so that multiple Controlled Devices can use the same controller.