Skip to content

frederikheld/pot-pourri

Repository files navigation

Pot Pourri

Pot Pourri helps you to keep your potted plants alive :-)

Comparison: Your plants with and without Pot Pourri

The system collects data from connected sensor devices (see the devices repository) an displays it on a web interface. This helps you to track the health of your plants and don't miss the right time when they need water.

It is also planned to add an event engine that triggers actors attached the connected devices on pre-defined events (like "moisture below x %"). This will allow for automatically watering the plants, regulating sun and ventilation, etc.

Note: parts of this project (mainly the mobile app) are being continued as closed source. If you want to know more about this project, have a look at gardeneers.social.

Architecture

Pot Pourri consists of several services that communicate via REST api interfaces or via their specific interfaces. Communication with the connected devices is conducted via the MQTT protocol.

Technical Architecture Design diagram of Pot Pourri

Note: According to the nature of the MQTT protocol, all MQTT communication is conducted via the broker. In order to keep the diagram clean, I visualized the communication between clients via an direct arrow between those clients.

The following sections give a brief abstract of the purpose of those services. Please see the readme of each service as well as the general readme for the services for more details!

mqtt-broker

This service is the backbone of the communication between the devices and the respective services.

I decided to use HiveMQ Community Edition, but any other broker works as well. If you have alread running a different broker, you can re-configure Pot Pourri to use that one. You could even use a publicly hostet server.

Learn more about the role of the MQTT broker in the MQTT protocol here.

persistence

The MQTT broker doesn't store data except for the last message that was sent on each topic. This is sufficient, if you want to only know the current state of your plants, but it doesn't give you historic data.

The purpose of the persistence service is to collect all values that were sent from Pot Pourri devices and store them in a database for later use.

It uses InfluxDB for this purpose, as it is specifically made for time-series data. InfluxDB is available at Port 8086 but has no own web interface!

InfluxDB is sided by Telegraf, which works as an adapter that receives MQTT messages, converts them into the InfluxDB data format, and stores them in the database.

The persistence service comes with the necessary configuration files and a docker-compose file that sets up all three tools to communicate with each other. This works out of the box, except you need a different configuration.

See persistence for details.

visualization

The visualization service offers dashboards to - surprise! - visualize the data collected from your devices. It connects via Docker networking to the persistence services and is set up ready to use.

It also comes with a dashboard template which you can use as a basis for your own dashboards.

Although Telegraf in the persistence service has the option to create dashboards as well, I'm using Grafana for visualization as it is not tied to InfluxDB alone but allows to connect to a variety of data sources.

See visualization for details.

webapp

Note: This service is work in progress!

The webapp will be a convenient user interace for mobile devices to interact with your plants. Compared to other services of Pot Pourri, the web app is designed for a better user experience by reducing the displayed data and interaction options to what's relevant in a specific context.

It will:

  • display the current health of your plants to tell you where you have to act at a glance
  • allow you to create and maintain plant profiles with information like max and min healty moisture for each plant individually
  • make it easy to integrate new devices into the Pot Pourri system

Right now it is capable of displaying the current moisture for each plant. All other features are not done yet and partly depend on planned features of metastore and persistence.

metastore

Stores meta information like plant profiles, device settings and links between such entities.

It is accessible by other services via a REST API.

Devices

You will find the devices that can monitor your plants in the separate repository.

Run Pot Pourri

Pot Pourri consists of several services that can run individually, but partly depend on each other. You will find details about prerequisites in the README.md of each service.

Prepare the environment

To run Pot Pourri you need to have Docker (instructions) and Docker-Compose (instructions) installed on your machine.

Clone this repository to a directory of your choice. This directory will referred to as . in this documentation.

$ git clone git@github.com:frederikheld/pot-pourri.git

The services come with an .env file that defines ports for each service. You do not need to change it, except you need a different setup.

Start the services

Note: These instructions assume that you're going to run all containers on the same machine. It is possible to run them on different machines but you might need to adapt the setup to your environment.

Each service comes with their own docker-compose file that can be used to start the service individually. Please note that some services depend on other service. Please read the respective README.md for more information.

Pot Pourri also offers a simple way to start services at once in the right order:

$ sh services/start_all.sh

Stop the services

In the same way as you started the services, you can either stop them individually via their respective docker-compose file or all at once via:

$ sh services/stop_all.sh

Update the services

To update the services, pull the latest version of this repository on the master branch and re-build the images.

All containers persist the relevant data in Docker volumes. Therefore you can easily shut them down and start them again. You can re-build all at once as shown above or each one individually.

If you do it individually, you can use the following docker-compose command to make sure that the images are being re-built and the containers are being properly re-started:

$ docker-compose up -d --build --force-recreate

start_all.sh will do exactly the same thing for each container in the right order.

Hint: you don't need to stop containers before you re-build them with docker-compose or start_all.sh! This will be done automatically.

Why the name Pot Pourri?

The name is a pun on many levels.

Firstly, a potpourri is defined as

a mixture of dried, naturally fragrant plant materials, used to provide a gentle natural scent (source: Wikipedia)

which your plants will hopefully never become if you use Pot Pourri.

It also refers to the colorful mixture of connected devices that can be used to collect data and act based on it.

And finally, the name is a composition of Pot from "potted plants" and Pourri as a word creation to describe "the thing that pours water into the pots".

I'm sorry to bother you with my weird humor. I really hope you're into puns ;-)