Auto Virtual Thermostat is a plugin for Vera Home Automation controllers. It uses a set of user-configurable sensors to supply the temperature data, and controls switched heating and cooling devices.
Make a donation to support this project.
Features
Configurable Temperature Sensor(s)
AVT allows you to set multiple sensing devices. The ambient temperature is the computed mean of the sensor readings.
To help prevent errant operation due to sensor failures (network issues, dead batteries, etc.), AVT examines the timestamp of each sensor's last temperature update. If it's not reasonably recent, the sensor is excluded. If the sensor is battery-operated, the timestamp of the sensor's last battery status update is also considered. Sensors on Vera, particularly battery-operated sensors, are notorious for "going away," and when they do, their last known state or measurement remains unchanged (as opposed to expiring and going to "null" or "error"). These additional checks are intended to provide a guard against dead and hanging sensors from affecting the operation of AVT. Please see the disclaimer and warnings below.
Temperature sensors appropriate for use with AVT will have the ability to send temperature reports at least every 30 minutes, and preferably every 15 minutes or less. The best sensors allow "delta-T" reports, where a report is sent when the temperature changes by more than a small amount. The sensor should also send battery reports (if battery powered) at least every two hours.
Heating and Cooling Device Control
AVT can control one each heating and cooling devices. This allows it to determine which device should be used to keep the room in the temperature range set (see Auto-Changeover, below). AVT will run only one of these devices at a time; they are not run simultaneously.
Economy/Comfort Setpoints
AVT maintains two sets of heating/cooling setpoints, one for use in "comfort" mode, and one for "economy" mode (this "Home" and "Away" like Nest thermostats). Switching between comfort and economy modes can be done on the dashboard, control panel, or by scenes or script commands.
Runtime Limit/Lockout
AVT monitors the continuous runtime of the controlled devices. If the device runs too long (two hours by default), AVT will shut the device off and lock its operation out for a while (30 minutes by default). This is intended to help prevent excessive runtime of the controlled device if the settings are unreasonable for the conditions (e.g. using a room air conditioner to try to reach 35°F--probably not going to happen), or the configured temperature sensing devices provide invalid values that are otherwise not detected as such (see above).
Fan Device Control
AVT can control a separate fan. The purpose of the fan is to help circulate heated or cooled air and provide a more even temperature in the conditioned space than might be achieved without it. AVT also supports "periodic" operation of the fan without heating or cooling, cycling the fan on for a few minutes each hour to help move air in the space.
Auto-Changeover
AVT supports auto-changeover, the ability to switch between heating and cooling as necessary to keep the temperature between two setpoints.
Schedule
AVT supports a single, simpe start/end daily schedule for its operation. VT will only provide heating or cooling between the specified times, and will remain idle at all other times during the day (or night).
Equipment Delay
AVT supports an equipment delay, intended primarily to protect compressor-driven cooling devices from "short-cycling"—having a very small delay between stop start. Short-cycling can cause excess pressure in compressors and lead to early failure. The delay allows the compressor's internal pressures to equalize before it is allowed to run again, resulting in a softer start.
Configuration
AVT allows you to specify one or more temperature sensors. When multiple temperature sensors are used, the temperatures of all eligible sensors are averaged. The "health" of the temperature sensors is gauged by how recent the sensor has updated itself, and if battery operated, if its last battery status is also recent (the definitions of recent for both conditions can be modified; see Advanced Configuration).
To add a temperature sensor, click the green-circled "+" icon. To remove a temperature sensor, change its dropdown to the first ("--choose--") entry (the dropdown will be removed when the page is redisplayed).
AVT allows you to specify a cooling device and a heating device separately. This allows AVT to operate in "auto-changeover" mode, automatically switching between heating and cooling as needed to maintain temperature between two setpoints. If you do not configure one of these devices, AVT will still operate, it will just be unable to perform the corresponding function (i.e. if you don't configure a cooling device, there can be no cooling).
AVT also allows you to configure a "fan" device. This can be used to power an additional fan to more evenly spread the heating/cooling around the room for a better result.
Finally, AVT allows you to specify a (single) schedule on which it will operate. You specify a start and end time, in 24-hour format. VT will only operate between these times, and remain "idle" outside of these times, regardless of sensed temperature.
After making configuration changes, you should reload the Luup engine to make sure the settings take effect immediately. A link is provided for this purpose under the schedule controls.
Advanced Configuration
AVT offers some tweak-able parameters by setting the value of state variables directly (there is no user interface for these options other than Vera's "Advanced" settings page, where state variables are displayed and may be modified).
Differential
The differential is the difference (in decimal degrees) between the setpoint temperature and the sensed temperature required for AVT to react. For example, if the thermostat is in "Heat" mode, the setpoint is 70°, and the differential is 2.0, the thermostat will not turn on the heating device until the sensed temperature is 68° (70 - 2 = 68) or less. In Cool mode, the cooling device would not be turned on until the temperature reaches 72°. The differential creates a "deadband" which provides hysteresis to prevent the thermostat from cycling the controlled device too frequently. The default is 1.0 (degrees).
HeatMaxRuntime & CoolMaxRuntime
The ____MaxRuntime parameters set the maximum time the corresponding controlled device is allowed to run before being "locked out." This is intended as a safety measure in case of an undetected fault with the configured temperature sensors--continuous operation of a heater or air conditioner can cause problems, or even be dangerous. If the runtime is exceeded, the device is turned off and SVT's operation is locked out for the "Lockout" period (see below). The default is two hours.
HeatingLockout & CoolingLockout
The ____Lockout period is the amount of time the corresponding controlled device is held off after hitting its maximum runtime. The default is 30 minutes.
MaxSensorDelay
The MaxSensorDelay is the maximum age of a temperature sensor's current temperature reading (in seconds) that may be considered viable. If the sensor report is older than this time, the sensor is excluded from calculation of the sensed temperature. If all sensors become ineligible, AVT enters a "failed" state and all heating/cooling ceases until a valid sensor is available. The default is 3600 seconds (one hour). Please read the "Troubleshooting" section below, and the caution in it, before adjusting this parameter.
MaxSensorBattery
The MaxSensorBattery is the maximum permissable age of a temperature sensor's last battery report. It operates like MaxSensorDelay above, just on the battery level report rather than the temperature report. The value applies only to battery-operated sensors. The default is 7200 seconds (two hours). Please read the "Troubleshooting" section below, and the caution in it, before adjusting this parameter.
MinBatteryLevel
The MinBatteryLevel is the minimum battery level a battery-powered sensor may report before it is deemed ineligible. Some sensors have problems with measurement "drift" when their batteries become weak. This variable allows the user to have AVT declare a sensor ineligible if its battery level falls below this threshold. Please read the "Troubleshooting" section below, and the caution in it, before adjusting this parameter.
EquipmentDelay
The EquipmentDelay variable determines how much time a controlled device (heating or cooling) must be off before the thermostat will turn it back on. This is specifically implemented for the benefit of compressor-run air conditioning units, where frequent cycling of the compressor can lead to early failure. The default is 300 seconds (five minutes).
FanOnDelayCooling & FanOnDelayHeating
These variables determine how much of a delay is provided between turning the controlled heating/cooling device on and turning on the fan device (in seconds). If greater than zero, the fan is started that many seconds after the heating/cooling device. If less than zero, the fan is started first, and the startup of the heating/cooling device is delayed. The default is 0 (the devices are started simultaneously).
FanOffDelayCooling & FanOffDelayHeating
These variables determine how much of a delay is provided between turning the controlled heating/cooling device off and turning off the fan device (in seconds). If greater than zero, the fan is turned off that many seconds after the heating/cooling device. If less than zero the fan is turned off first, and the shut-off of the heating/cooling device is delayed. The default is 60 (the fan runs for 60 seconds after the heating or cooling device shuts off).
ImperiHome Integration
AVT (as of v1.4) implements the ImperiHome ISS API, which allows ImperiHome to see and control AVT devices. To add your AVTs to your ImperiHome configuration:
- Open the ImperiHome app;
- From the menu, choose My Objects;
- Click Add a new object;
- Choose ImperiHome Standard System;
- In the Local API base URL enter: http://your-vera-ip/port_3480/data_request?id=lr_AutoVirtualThermostat&action=ISS
- Click the Next button.
ImperiHome should then connect to AVT on the Vera, take inventory, and display the thermostats. Controls operate as is typical for ImperiHome's thermostat interface, and should be self-explanatory.
Troubleshooting
AVT Shows Warning Triangle/Exclamation Mark
The red warning triangle with an exclamation mark means AVT is offline. The most common reason for this is problems communicating with your temperature sensors (particularly if you use only one). Because AVT is meant to control heating/cooling applicances, it expects you to update your temperature sensor configuration for frequent termperature and health updates. In order to be considered "eligible," your temperature sensor must:
- Report temperature at least once per hour;
- Report battery status at least one every two hours;
- Have a battery level >= 1%;
- Have no recent errors in Z-Wave communication (as determined by Vera's software and the device status it sets for the sensor as a result).
The easiest way to tell which of the above is causing your AVT to go off-line is to look at the Vera (or openLuup) log file. AVT writes the word "ineligible" in all messages related to the disqualification of temperature sensors, so if you search the log for this word, you will find the cause.
If AVT is logging "ineligible, comm failure", then your Z-Wave (or other) communication with the device is the problem and you need to resolve that. There are no settings in AVT available to compensate for this issue.
If AVT is logging "ineligible, last temperature update at (time) is more than (time) ago", then your temperature sensor is not sending updates frequently enough. Update your sensor configuration to send reports more frequently. Since you are trying to get accurate temperature control, values less than 30 minutes are typical, and 15 minutes or less is recommended. Some sensors, the best sensors really, allow reports on delta-temperature, that is, they send a report when the temperature changes by more than a set amount, as often as needed. If your sensor offers this feature, enabling it and setting the differential to 0.5 degrees or less is recommended (but in no case more than 1 degree). Sensors that cannot adjust report frequency or report differential and report at intervals greater than 30 minutes are not appropriate or safe to use with AVT.
If AVT is logging "ineligible, last battery report (time) is more than (time) ago", then your temperature sensor is not sending battery level updates frequently enough. Adjust the configuration of your temperature sensor to send more frequent battery reports. You should also check Vera's "polling interval" for the sensor. If your sensor does not have the ability to send more frequent battery reports, you can adjust the MaxSensorBattery state variable to a higher number of seconds (up to 86400 = 24 hours), and adjust MinBatteryLevel to a number like 10 or 20 (percent). This will reduce AVT's sensitivity to infrequent battery level reports, but make it more sensitive to low battery levels to compensate for that.
If AVT is logging "ineligible, battery level (level) < allowed minimum", then the battery in your sensor needs to be replaced. The MinBatteryLevel state variable sets the value at which this triggers. The default is 1 (percent). If your temperature sensor loses accuracy as its battery drains, set MinBatteryLevel to the value at which the sensor becomes unacceptably inaccurate.
CAUTION! The author does not recommend disabling any of the tests, or setting unreasonable values for any of the controlling state variables to mitigate sensor eligibility problems. Improper values can affect the safety of AVT in your environment (and not all environmental parameters and equipment can be foreseen and addressed). If your sensor doesn't work well, get a better sensor. Please read the further disclaimer below, which is included as a license condition for this software.
Disclaimer, Warnings, License
AVT attempts to provide automatic control of devices, but cannot be aware of every condition that may affect the desirability or safety of those devices to run under all circumstances. The system on which it is installed may "hang" or "crash," sensors and switches can go offline or provide invalid/incorrect readings, interference can degrade the reliability of communications, etc. The failure modes are too numerous and the limitations of plugin operation on the target system too varied to provide a "fail safe" plugin for all conditions and circumstances. For this reason, AVT is appropriate for use only in supervised, attended operation, when competent adult humans can detect conditions and mitigate any problems that could lead to undesired operation or a hazardous condition. By running AVT, you agree that you understand and accept the appurtenant risks inherent with running this software and the devices you choose to control, and you agree to assume those risks entirely upon yourself, releasing the author from any liability or tort in any form from whatever cause arising. The author makes no warranty with regard to the performance of AVT, including but not limited to warranties of fitness for a particular purpose, or that it is or will run error-free. If you do not agree to indemnify, defend, and hold harmless the author from any cause, claim, or loss arising related to your use of AVT (including all costs of my defense), then you may not and must not use AVT or any part thereof in any way. AVT is offered under GPL 3.0; see the LICENSE file on the AutoVirtualThermostat GitHub Repository for additional terms.