Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 35 additions & 39 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,71 +1,67 @@
# Poupool - The swimming pool controller
# 🏊 Poupool - The swimming pool controller

[![Build Status](https://travis-ci.com/lostcontrol/poupool.svg?branch=master)](https://travis-ci.com/lostcontrol/poupool)
[![Poupool](https://github.com/lostcontrol/poupool/actions/workflows/poupool.yml/badge.svg)](https://github.com/lostcontrol/poupool/actions/workflows/poupool.yml)

Poupool is a swimming pool control software.
**Poupool** is a swimming pool control software.

It is based on [Transitions](https://github.com/pytransitions/transitions),
[Pykka](https://www.pykka.org) and [Paho MQTT](https://github.com/eclipse/paho.mqtt.python).
The user interface is built using the excellent home automation server
[openHAB](http://www.openhab.org). Though, any MQTT client could be used to interact with the
The user interface is built using an excellent home automation server like
[openHAB](http://www.openhab.org) or [Home Assistant](https://www.home-assistant.io/). Though, any MQTT client could be used to interact with the
system.

![The swimming pool](docs/images/pool-01.jpg)

This is meant as a personal project and will likely never be a fully-featured software. However, it
would be awesome to see it running somewhere else. Poupool runs on a Raspberry Pi 3 Model B and most
of the hardware is COTS (commercial off-the-shelf). If you want more information, feel free to
This is meant as a *personal project* and will likely never be a fully-featured software. However, it
would be awesome to see it running somewhere else. Poupool runs on a **Raspberry Pi 3 Model B** and most
of the hardware is COTS (*commercial off-the-shelf*). If you want more information, feel free to
contact me.

Originally, I wanted to experiment with asyncio but finally chose to go with some more traditional
Originally, I wanted to experiment with `asyncio` but finally chose to go with a more traditional
approach (actor model and finite state machines).

Poupool currently controls filtration (including backwash), heating (heat pump), pH and
chlorination, cover, lights and all the pumps and valves of the system. It is used for an overflow
Poupool currently controls **filtration** (including backwash), **heating** (heat pump), **pH and
chlorination**, **cover**, **lights** and all the pumps and valves of the system. It is used for an overflow
swimming pool so that adds some complexity to the control process (e.g. monitoring of the retention
tank water level).

The main interaction with the system is done through modes. Here are some of the main ones:

* **eco** : cover close, filtration, pH, chlorination and heating are automatic
* **standby** : cover open, no overflow
* **overflow** : cover open, overflow, chlorination is forced
* **comfort** : cover open, no overflow, heating is forced
* 🌿 **eco** : cover close, filtration, pH, chlorination and heating are automatic
* ⏸️ **standby** : cover open, no overflow
* 🌊 **overflow** : cover open, overflow, chlorination is forced
* 🛋️ **comfort** : cover open, no overflow, heating is forced

Several other features are available like a wintering state stiring the pool to avoid as long as
possible to have the water freezing, a stiring feature when the cover is closed to dissipate the
Several other features are available like a **wintering state** stirring the pool to avoid as long as
possible having the water freeze, a stirring feature when the cover is closed to dissipate the
heat forming just under the cover, the control of a swimming pump and more.

Here is a screenshot of the main menu in openHAB 2.5M1:

![openHAB main menu](docs/images/openhab-01.png)

Of course, you can use the iOS or Android openHAB clients, write your own HABPanel interface or
even use the REST API provided by openHAB.
Of course, you can use the iOS or Android openHAB clients or Home Assistant companion apps, write your own HABPanel or Lovelace dashboards, or
even use the REST API provided by these systems.

## Dependencies
## 📦 Dependencies

These are the external dependencies that can be installed via `uv`. You will also need Python 3.11+.
These are the external dependencies that can be installed via `uv`. You will also need **Python 3.11+**.
Best is to setup a virtual environment by running `uv sync`.

Frameworks:
### 🏗️ Frameworks:
* **Pykka**
* **transitions**
* **paho-mqtt**
* **astral**

* Pykka
* transitions
* paho-mqtt
* astral
### 🍓 Raspberry Pi:
* **RPi.GPIO**
* **adafruit-circuitpython-ads1x15**
* **adafruit-circuitpython-mcp4725**

Raspberry Pi:
### 📱 User interface:
* **openHAB 2.5** or **Home Assistant**

* RPi.GPIO
* adafruit-circuitpython-ads1x15
* adafruit-circuitpython-mcp4725

User interface:

* openHAB 2.5

Development tools:

* ruff
* pytest
### 🛠️ Development tools:
* **ruff**
* **pytest**
Loading