https://github.com/adpeace/boilerio
A heating control system
https://github.com/adpeace/boilerio
boiler heating-control home-automation thermostat
Last synced: 5 months ago
JSON representation
A heating control system
- Host: GitHub
- URL: https://github.com/adpeace/boilerio
- Owner: adpeace
- License: mit
- Created: 2017-04-06T23:35:29.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2025-09-04T22:16:46.000Z (9 months ago)
- Last Synced: 2026-01-03T23:31:03.455Z (5 months ago)
- Topics: boiler, heating-control, home-automation, thermostat
- Language: Python
- Homepage: https://andyhacks.com
- Size: 221 KB
- Stars: 6
- Watchers: 3
- Forks: 4
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# The BoilerIO Software Thermostat
BoilerIO can control heating in your home. Code is provided here to connect
with Danfoss RF receivers though other implementations could easily be added,
and to receive temperature updates over MQTT in a format described later in this
README.
This has been tested with the Danfoss RF transciever code in the thermostat.git
repository at https://github.com/adpeace/thermostat.git.
No warranty is provided: please be careful if you are messing with your own
heating system.
For more information, please see https://andyhacks.com.
## Installation
More details on installation to be written. There are several components that
need to be configured:
1. The web application and database, to provide the online component.
1. The local scheduler and boiler interface.
1. The sensor inputs
You can install from the repository to get a specific version, such as the
latest development version not yet published to PyPI, or install via `pip` from
PyPI for a recent tested version by running:
```
pip install boilerio
```
To install from the git repository, first check it out then install using `pip`:
```
$ git clone https://github.com/adpeace/boilerio.git
$ cd boilerio
$ pip3 install .
```
Use `-e` to `pip` to install in development mode (i.e. just link to the
checked-out source instead of installing it).
### Raspberry Pi Quickstart to get MQTT-based on/off control working
You can run these steps on a Raspberry Pi with a fresh SD card that has the Buster version of Raspbian. You can ssh to the Raspberry Pi, then copy/paste these commands into the terminal. You'll need a transceiver device such as a JeeLink with the `thermostat` firmware (available at https://github.com/adpeace/thermostat) plugged in to use this.
```
sudo apt install -y python3-pip git
git clone https://github.com/adpeace/boilerio.git
cd boilerio
sudo pip3 install --upgrade pip # good practise but not mandatory
sudo pip3 install .
sudo mkdir /etc/sensors
sudo bash -c 'cat >/etc/sensors/config' < -u -P -t heating/zone/demand \
-m '{"command": "L", "thermostat": 47793}'
done
```
## boilersim
This is a trivial simulator intended to help debug and improve the thermostat.
It follows a really simple heating/cooling model and generates a table as
output.
To run, use a command-line such as:
```
$ boilersim -r 18 19.5 600
```
The `-r` option introduces some random noise into the temperature readings
generated by the simulation when passing them to the controller.
The first positional argument is the starting indoor temperature to simulate.
The second argument is the target temperature. The third argument is
the simulated runtime in minutes.
This program produces logging output to stderr, and a space-separated output to
stdout. The output is similar to:
```
...
1.0 0 0 17.9964773317 17.9876417779 0 0 0
...
```
The columns are:
1. The time into the simulation, in minutes
2. The amount of time in that minute that the boiler was on for in the
simulation.
3. The current duty cycle of the boiler in the simulation.
4. The current simulated room temperature
5. The fake temperature reading passed to the controller including any error
introduced by the `-r` option.
6. The current value of the proportional term of the PID controller.
7. The current value of the integral term of the PID controller.
8. The current value of the differential term of the PID controller.
You can use the `plot\_sim.gpi` gnuplot script to plot the output of the
simulation. E.g.:
```
$ boilersim -r 18 19.5 600 2>log >sim_data
$ gnuplot plot_sim.gpi
```
The gnuplot script assumes the simulation output is saved to a file called
`sim\_data`.
# Config file
Other than `boilersim`, a config file is needed for the programs here. This is
to help make them usable as daemons.
```
[mqtt]
host = raspi.lan
user = user
password = imnottellingyou
[heating]
# Various MQTT topic names to use. These can be anything but are specified in
# the config in case you have other software that constrains your choices, and
# ensures they are consistent across apps.
info_basetopic = heating/zone/info
demand_request_topic = heating/zone/demand
thermostat_schedule_change_topic = heating/thermostat_control/update
scheduler_db_host = hub.lan
scheduler_db_name = scheduler
scheduler_db_user = scheduler
scheduler_db_password = imnottellingyou
scheduler_url = https://your_url
scheduler_username = your_user
scheduler_password = imnottellingyou
```