Metadata-Version: 1.1
Name: boilerio
Version: 0.0.4
Summary: A software thermostat and heating control system
Home-page: https://github.com/adpeace/boilerio.git
Author: Andy Peace
Author-email: andrew.peace@gmail.com
License: MIT
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:
        
        1. The web application and database, to provide the online component.
        2. The local scheduler and boiler interface.
        3. 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:
        
        1. 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``.)
        
        2. 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.
        
        3. The web app. This is the ``schedulerweb`` Flask app. The recommended
           configuration is for this to be proxied through nginx and run inside
           uwsgi.
        
        4. 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:
        
        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
        
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: License :: OSI Approved :: MIT License
