A software thermostat and heating control system
Project description
The BoilerIO Software Thermostat
BoilerIO can control heating in a zone of 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://hackingathome.wordpress.com.
Installation
More details on installation to be written. There are several components that need to be configured:
The web application and database, to provide the online component.
The local scheduler and boiler interface.
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' <<EOF [mqtt] host = mqtt_hostname user = mqtt_username password = mqtt_password [heating] info_basetopic = heating/zone/info demand_request_topic = heating/zone/demand EOF
Now use a text editor such as nano to edit /etc/sensors/config and replace the MQTT server details with your own.
Now run boiler_to_mqtt /dev/ttyUSB0 (replacing /dev/ttyUSB0 with the location of the Danfoss transceiver device, e.g. your JeeLink; JeeLink will probably show up at that device name though if you don’t have other USB devices connected).
The web app
To run the scheduler flask application for development, using flask run:
$ FLASK_APP=boilerio/schedulerweb.py flask run
The scheduler
The scheduler comes in four parts:
The database. You need to be running postgres; once you have installed postgres you can create a database user and database for the scheduler, then user scheduler.sql to create the requisite tables. (This currently assumes the databsae and a role exists called scheduler.)
The controller. This is the scheduler Python script. Ensure this daemon is running to control the boiler relay and update the cache of the current temperature in the backend web app.
The web app. This is the schedulerweb Flask app. The recommended configuration is for this to be proxied through nginx and run inside uwsgi.
The web-based UI. This talks to the schedulerweb app and presents a UI where the current temperature and schedule can be configured.
Example uWSGI configuration for schedulerweb (assuming you have the Python package installed) - this can be placed in /etc/uwsgi/apps-available on Ubuntu’s version of uwsgi:
[uwsgi] socket = /var/www/boilerio/thermostat.sock module = boilerio.schedulerweb:app logto = /var/log/uwsgi/boilerio/thermostat.log uid = boilerio gid = www-data chmod-socket = 664
scheduler: The controller
The local scheduler component provides the timer and thermostat behaviour: it gets the target temperature periodically from the web service and controls the boiler by sending messages to the boiler_to_mqtt program.
The scheduler takes no arguments: the configuration will come from the web service.
boiler_to_mqtt
The boiler_to_mqtt script implements an MQTT-topic based interface on top of the serial protocol provided in the thermostat.git repository. In short: it turns the boiler on and off via MQTT. The serial interface in thermostat.git is designed to interact with a Danfoss RF thermostat receiver; if you wanted to use a different receiver you can substitute a different service.
Ordinarily you’d leave this service running so that other services can turn the boiler on/off as needed.
This service and others in this repository use a common configuration file. See below for more information.
You can send learn packets in a loop with a simple shell loop, if you have the mosquitto clients installed and are running the boiler_to_mqtt.py script:
echo -n "Learning mode - program boiler then hit enter... " while ! read -t 1 ; do mosquitto_pub -h <host> -u <username> -P <passwd> -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:
The time into the simulation, in minutes
The amount of time in that minute that the boiler was on for in the simulation.
The current duty cycle of the boiler in the simulation.
The current simulated room temperature
The fake temperature reading passed to the controller including any error introduced by the -r option.
The current value of the proportional term of the PID controller.
The current value of the integral term of the PID controller.
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
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.