Plugins/Smart Virtual Thermostat.html

Smart Virtual Thermostat python plugin for Domoticz

IMPORTANT NOTE: This is Beta software, so you use it at your own risk…

Current version: 0.4.4 (October 7, 2018)

Author: Logread (aka 999LV on Github)

Plugin objective:

Easily implement in Domoticz an advanced virtual thermostat based on time modulation and self learning of relevant room thermal characteristics (including insulation level) rather then more conventional hysteresis methods, so as to achieve a greater comfort. It is a port to Domoticz of the original Vera plugin from Antor as described at [1]. All the technical explanations about the logic behind the smart virtual thermostat are given there.

In addition, the thermostat offers the following features:

1. Normal/Eco modes, for instance for night v.s. day temperature control
2. Pause mode, for instance to stop heating when a door or window is open for a certain time

IT DOES NOT DEAL WITH COOLING ! ONLY HEATING IS SUPPORTED !

This plugin requires the following input sensors and output switch(es) to operate:

1. Inside Temperature Sensor(s): Mandatory - One or more Domoticz temperature devices providing ambient temperature data to the thermostat
2. Outside Temperature Sensor(s): Optional - One or more Domoticz temperature devices providing outside temperature data to the thermostat
3. Heater Switch(es): One or mode Domoticz switch devices driving heaters/boiler(s) on an on/off basis.

This plugin will create the following devices in Domoticz:

1. "<plugin-name> - Thermostat Control": sets the status of the thermostat (off, auto mode, forced mode)
2. "<plugin-name> - Thermostat Mode": sets the mode for temperature control (normal, economy), using the relevant setpoint (see below for setpoint devices). This can be used for instance with a timer to switch between night and day operation.
3. "<plugin-name> - Thermostat Pause": if set to "On", will force the thermostat in pause mode after a delay (see Parameters section below) and conversely resume normal operation if set to "Off". This can be switched for instance with a small blockly or lua domoticz script to pause heating when a window or door is open.
4. "<plugin-name> - Setpoint Normal": sets the temperature target for the normal mode
5. "<plugin-name> - Setpoint Economy": sets the temperature target for the economy mode
6. "<plugin-name> - Thermostat Temp": displays the current ambient temperature (average of the values of the internal temperature sensors as provided in the hardware parameters). That device is "hidden" by default and can obviously be added to your domoticz dashboard from the "Setup/Devices" menu.

Here is are screenshots of all these devices:

In addition, the plugin will create one User Variable in your domoticz setup (labeled "<plugin-name>-InternalVariables") that will be used to permanently store some critical persistent variables required by the plugin such as the heating and insulation coefficients it learns and uses). If you manually delete this user variable and immediately restart domoticz, the plugin will recreate it with its default parameters and all past learning will be lost). If you mess with it by editing it manually (there should be no need for that) and the format is no longer a valid python dictionary that the plugin can work with, then default values will be used by the plugin again and all past learning will be lost.

Prerequisites:

1. The Domoticz system on which the plugin runs must be version 3.7418 minimum (otherwise Domoticz might crash due to a bug in the python plugin framework).
2. The python plugin system must be installed (see the instructions at https://www.domoticz.com/wiki/Using_Python_plugins ).

Installation:

The below instructions are for a Raspberry Pi Linux platform… I have not tested this on other platforms (e.g. Windows) but I assume a bit of search on the Domoticz forum can help you…

1. Open a shell session
2. Navigate to the directory holding your Domoticz installation (typically ~/domoticz)
3. Perform the following commands within the shell:

cd plugins
mkdir SVT
sudo apt-get update
sudo apt-get install git
git clone https://github.com/999LV/SmartVirtualThermostat.git SVT
cd SVT
sudo chmod +x plugin.py
sudo /etc/init.d/domoticz.sh restart

Now connect to Domoticz with your browser. If not already done, configure domoticz to allow new devices (settings page) and then go to the “Setup/Hardware” page and select the “Smart Virtual Thermostat” type from the drop-down list. You should now see the following:

[[File:HWPage041.JPG]

1. Enter the IP address of the domoticz system on your LAN (or '127.0.0.1' (without brackets or quotes) if the plugin runs on the same machine as the target domoticz. Contrary to the screenshot, do not use 'localhost' as this can yield errors on some systems).
2. Enter the Port used to access the domoticz system at the above IP (e.g. 8080)
3. Enter the username / password required by domoticz (if not disabled)
4. Enter the relevant thermostat parameters required or optional, as per the "Parameters" section below.
5. “Add” the new hardware…

In case something does not work, enable the “Debug” mode for the plugin in the “Settings/Hardware” page and check the logs for errors and send me a pm @logread on the Domoticz forum with the description of the error(s) and copy of the relevant log entries.

Parameters:

1. Inside Temperature Sensors: Enter the domoticz "idx" (i.e. device "number") of at least one temperature sensors. Multiple sensors can be provided in a comma separated format (e.g. 6,7,12) and the virtual thermostat will average their values to be used as ambient temperature. Note that if no inside temperature sensor is provided the virtual thermostat will switch itself off.
2. Outside Temperature Sensors: Enter the domoticz "idx" (i.e. device "number") of one or more outside temperature sensors. Multiple sensors can be provided in a comma separated format (e.g. 14,15) and the virtual thermostat will average their values to be used as the outside temperature. Note that if no outside temperature sensor is provided the virtual thermostat will just ignore the outside temperature in its calculations.
3. Heating Switches: Enter the domoticz "idx" (i.e. device "number") of at least one heater or boiler on/off switches. Multiple sensors can be provided in a comma separated format (e.g. 6,7,12) and the virtual thermostat will actuate all as required. Note that if no inside temperature sensor is provided the virtual thermostat will throw errors.
4. Apply minimum heating per cycle [new in version 0.4.1]: Define behavior of thermostat when a minimum heating per cycle parameter is provided.
   1. If set to "only when heating required" (default option), then the minimum heating will only be applied when the desired temperature is not reached. This is for instance useful when driving central heating boilers that have a certain inertia.
   2. If set to "always" then the minimum heating at each heating/calculation cycle will always be applied, regardless of whether the desired temperature is reached. This is for instance useful for floor heating systems with very high thermal inertia, where it is better to avoid the floor cooling too much even if no heating is actually needed.
5. Calculation cycle, Minimum Heating time per cycle, Pause On delay, Pause Off delay, Forced mode duration: Due to limitations of the domoticz python plugin platform, a number of additional parameters have been grouped in a single one, with comma separated values. This is unfortunately complex, but this line includes advanced parameters that can be critical to the proper operation of the smart virtual thermostat:
   1. Calculation cycle: This is the time in minutes between two thermostat calculations. This needs to be set depending on the thermal inertia of your physical room and heater system and might require some tweaking. Note for starters that the default 30 minutes appears well suited for a discrete electrical convectors setup and that 60 minutes or more value might be a better fit for a whole house conventional fuel or gas boiler central heating setup.
   2. Minimum Heating per cycle: This is the minimum % that the heater(s) must be on in a given calculation period (see above 'Apply minimum heating per cycle' parameter). Value can be from 0 to 100.
   3. Pause On delay: This is the number of minutes that the "Pause" switch must be on before the thermostat actually switches the heating off. This is very useful to allow a door to be opened briefly then closed again without any impact on the thermostat, while leaving a door open for a longer time would then cause the thermostat to switch off the heating to avoid wasted heating.
   4. Pause Off delay: Conversely from the previous parameter, the number of minutes that the "Pause" switch must be off before the thermostat resumes its normal operation.
   5. Forced mode duration: The time in minutes that the thermostat will force heating when the "Forced" mode is selected. After that duration, the "Auto" mode will be active.

Updating to last version:

1. Open a shell session
2. Navigate to the directory holding your Domoticz installation (typically ~/domoticz)
3. Perform the following commands within the shell:

cd plugins/SVT
git reset –-hard
git pull --force
sudo chmod +x plugin.py
sudo /etc/init.d/domoticz.sh restart