Home automated terrarium/aquarium or other enclosed environment with a Raspberry Pi
Clone or download
Latest commit 98f2404 Oct 17, 2018
Failed to load latest commit information.
audio First attempt to add an audio system with audio files and playlists. #42 Nov 5, 2017
chirp-rpi @ 12fd772 Add support for Chirp moisture/temperature/brightness sensors. https:… May 16, 2018
contrib Fix file uploading May 24, 2018
energenie-connect0r @ 12ca24a Add support for Energenie LAN power switches. #95 Feb 13, 2018
fonts Moved from v1 to v2 Aug 20, 2016
gentelella @ edadb19 Update submodules Aug 15, 2018
locales Second attempt light state for webcams. #184 Sep 9, 2018
log Added logging to disc (part 1) Nov 27, 2016
screenshots Add files via upload Apr 9, 2018
static Update submodules Sep 29, 2018
views Second attempt light state for webcams. #184 Sep 9, 2018
webcam Add webcam archiving. Testing n ow Apr 2, 2018
.gitchangelog.rc Update changelog Feb 22, 2018
.gitignore Ignore webcam images and archive Sep 9, 2018
.gitmodules Add support for Chirp moisture/temperature/brightness sensors. https:… May 16, 2018
CHANGELOG.md Update changelog Aug 4, 2018
LICENSE Added some documentation Aug 20, 2016
README.md Update README.md Aug 21, 2018
defaults.cfg Update version number Aug 4, 2018
install.sh Fix installer when updating with git Aug 4, 2018
logging.cfg Add logging explanations Jun 17, 2018
start.sh Updated some logging and installer messages Jun 11, 2018
terrariumAnalogSensor.py Add sensor data caching for sensors with multiple sensor types. Shoul… Jul 25, 2018
terrariumAudio.py Ignore non usefull audio devices. #191 Oct 17, 2018
terrariumBluetoothSensor.py Update light sensors to use LUX value as default. This means that Chi… Jul 27, 2018
terrariumCollector.py Fix graphs for dc-dimmer. #178 Aug 21, 2018
terrariumConfig.py Fix config upgrade. #155 Jun 1, 2018
terrariumDisplay.py Add serial LCD display support (un tested). #193 Oct 16, 2018
terrariumDoor.py Finetuning Jul 1, 2018
terrariumEngine.py Second attempt light state for webcams. #184 Sep 9, 2018
terrariumEnvironment.py Add CO2 support and update fertility environments. #177 Aug 11, 2018
terrariumGPIOSensor.py Add sensor data caching for sensors with multiple sensor types. Shoul… Jul 25, 2018
terrariumI2CSensor.py Add sensor data caching for sensors with multiple sensor types. Shoul… Jul 25, 2018
terrariumLogging.py Finetuning Notifications. Renamed LCD to Display for general name and… Jul 7, 2018
terrariumNotification.py Increase Telegambot retries. Is needed for SSL issues during startups… Jul 27, 2018
terrariumPI.py Fix UTF-8 XML parsing. Now the software is fully UTF-8 supported. #179 Aug 13, 2018
terrariumSensor.py Add CO2 support and update fertility environments. #177 Aug 11, 2018
terrariumSwitch.py Updating dimming frequency based on issue #178 Aug 21, 2018
terrariumTranslations.py Second attempt light state for webcams. #184 Sep 9, 2018
terrariumUtils.py Make timers with zero on and off duration period run for the whole pe… Jul 27, 2018
terrariumWeather.py Add missing skyicon Aug 21, 2018
terrariumWebcam.py Fix broken Webcam. #192 Oct 16, 2018
terrariumWebserver.py Update data gaphing and finetuning SQL Jul 8, 2018


TerrariumPI 3.8.4

Software for cheap home automation of your reptile terrarium or any other enclosed environment. With this software you are able to control for example a terrarium so that the temperature and humidity is of a constant value. Controlling the temperature can be done with heat lights, external heating or cooling system. As long as there is one temperature sensor available the software is able to keep a constant temperature.

For humidity control there is support for a spraying system. The sprayer can be configured to spray for an X amount of seconds and there is a minumal period between two spray actions. Use at least one humitidy sensors to get a constant humidity value. In order to lower the humidity you can add a dehumidifier.

The software is that flexible that there is no limit in amount of sensors, relay boards or door sensors. The usage can be endless. All power switches have support for timers to trigger based on a time pattern.

Think off:

  • Terrarium (wet or dry)
  • Aquarium
  • Tanks with animals or plants
  • Growhouse

And all this is controlled with a nice webinterface based on Gentelella a Bootstrap 3 template.

Table of Contents

  1. Features
  2. Translations
  3. Installation
  4. Updating
  5. Hardware
    1. GPIO numbering
    2. New hardware
  6. Remote data
  7. Screenshots
  8. Testing
  9. About


  • Controlling electronic devices like lights, sprayers, heating, cooling, water pump equipment etc
  • Support for dimming electronic devices
    • Manual dimming through web interface
    • Predefined on and off dimming durations
    • Predefined on and off dimming percentages
    • Predefined dimming steps for environment system (heater and cooler)
  • Support for timmers in powerswitches and environment #72
    • Predefined start and stop times based on timer or weather
    • Predefined on and off durations in minutes
  • Support for Energenie USB and LAN powerswitches EG-PM(s)2
  • Support for multiple type of sensors
    • Temperature
    • Humidity
    • Moisture
    • Conductivity
    • Distance
    • pH
    • Light intensity
    • UV A and B
    • Fertility
  • Support for webcams and native Raspberry Pi cam out of the box
  • Support for analog devices through a MCP3008
    • Support for PH probe SKU SEN0161
  • Support for MiFlora Bluetooth sensors
  • Open door detection. This can be used in different environment parts
  • Total power and water usage for costs calculation
  • Lights control based on sun rise and sun set or timers
  • Rain control based on humidity sensors and timers
  • Temperature control based on temperature sensors or timers
    • Variable day and night difference for min and max temperature
  • Watertank level control based on ultrasonic sound range sensors
  • Weather forecast from external source for lighting schema
  • Temperatures in Celsius or Fahrenheit
  • Distances in centimetres or inches
  • Alarm detections
  • Audio support through interal audio jack or USB soundcards #42
    • Create playlists (loop and repeat)
    • Volume controle in the webinterface
    • Uploading audio files through webinterface
    • Audio meta data support (mediainfo)
  • Remote temperature and humidity sensors through HTTP(S) JSON API's. JSON Data format can be found on Remote data wiki.
  • Display support
    • LCD 16x2 or 20x4 screens
    • OLED based on SSD1306
  • Notifications system. Custom messages for custom actions with use of variables in the messages
    • Get notifications through
      • Email
      • Twitter (DM)
      • Pushover
      • Telegram bot
      • Display
    • Notifications for
      • Environment part low and high alarm
      • Sensor high and low measurements
      • Power switch toggle on and off
      • Open and close doors
      • System error and warning messages

It is currently controling my reptile terrarium for more then three years! And my Madagascar Day Gecko is very happy with it!


The software has support for the following languages:

  • English
  • Dutch
  • German
  • Italian
  • France
  • Norwegian

Your language not in the list or not up to date? Create your own language translation


The installation expects a Pi with working network and ssh. It is tested with Raspbian Stretch Lite. For now the Full version is not working somehow.... So use the lite image!

  1. Get a working Raspberry Pi and login as user 'pi'
    ssh pi@[raspberry_ip]
  2. Install git
    sudo apt -y install git
  3. Clone this repository and submodules!
    git clone --recursive https://github.com/theyosh/TerrariumPI.git
  4. Enter the new TerrariumPI folder
    cd TerrariumPI
  5. Run the installer script and wait
    sudo ./install.sh
  6. Reboot Raspberry PI to get all the needed modules loaded
    sudo reboot
  7. Go to the webinterface at http://[raspberry_ip]:8090

All needed options and modules are setup by the installer script. This means that I2C and 1Wire overlay are enabled by default.

Make sure that your Pi is secured when you put it to the Internet. Would be a shame if TerrariumPI gets next fictum of 'A smart fish tank left a casino vulnerable to hackers' :P


This updating is based on that the software is installed with the steps in the Installation above. When updating between release versions it will take more time due to database updates and cleanups. This can be seen in the logfile.

  1. Get a working Raspberry Pi and login as user 'pi'
    ssh pi@[raspberry_ip]
  2. Enter the TerrariumPI folder
    cd TerrariumPI
  3. Update the new code with git
    git pull
  4. Re-run the installation script in order to update software dependencies
    sudo ./install.sh
  5. Restart TerrariumPI according to: https://github.com/theyosh/TerrariumPI/wiki/FAQ#how-to-restart-terrariumpi

Now clear your browser cache and reload the webinterface. A brand new version should be running.


This software requires a Raspberry Pi and some extra hardware in order to run and work. The bare minimun and tested hardware is

  • Raspberry PI
    • Pi 2
    • Pi 3
    • Zero
  • Power relay board
    • USB versions (Serial and Bitbang)
    • GPIO versions
    • PWM Dimmer versions
  • Temperature/humdity/ultrasonic/PH sensors DHT11, DHT22, AM2303, DS1820, HIH4000, HC-SR04, SEN0161, etc through

Full list of supported hardware

GPIO numbering

All hardware that connects to the GPIO pins use Physical GPIO numbering (1 - 40). The software will translate it to BCM if needed for a supported device or sensor. More information about GPIO pin numbering

For the analog devices use numbers of the channel on the analog device which is from 0 to 7 (8 channels). Also the software expect the analog MCP3008 on GPIO ports 19,21,23,24 physical (default). More information about GPIO pin numbering

New hardware

If there is some other hardware which is not working with TerrariumPI, open an issue on Github and we will try to support it. Raspberry Pi Zero is not tested.

Remote data

It is possible to use external sensor data that is available through HTTP(S) in JSON format. This way you can combine multiple Raspberry Pi's with TerrariumPI running to one single system. By using multiple Rapsberry PI's you can cover a bigger area. But there are limitations.

Currently it is READONLY. So you can read out remote sensors and switches but you cannot control the remote switches. But this way you can combine the power swiches total costs and power usage.

more information is here: Remote data wiki


(made on a very big screen :P )


TerrariumPI 2.5 Dashboard screenshot


TerrariumPI 2.5 Sensors settings screenshot

Adding sensors

TerrariumPI 2.5 Sensors settings screenshot adding a new sensor

Power switches

TerrariumPI 2.5 Power switches settings screenshot

Environment setup

TerrariumPI 2.5 Environment setup screenshot

System settings

TerrariumPI 2.5 System setup screenshot

More screenshots can be found here


Free tested with BrowserStack for opensource BrowserStack


A live version is running at: https://terrarium.theyosh.nl/index.html. Go to 'Help' menu for more information about used hardware, software and how to setup.