AutoVirtualThermostat Plugin for Vera Home Automation Controllers

AVT's Control PanelAuto 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.

Donate to this projectMake 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.

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).

AVT on the Vera DashboardFan 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

ConfigurationAVT 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).

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).

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.

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:

  1. Open the ImperiHome app;
  2. From the menu, choose My Objects;
  3. Click Add a new object;
  4. Choose ImperiHome Standard System;
  5. In the Local API base URL enter: http://your-vera-ip/port_3480/data_request?id=lr_AutoVirtualThermostat&action=ISS
  6. 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.

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 Vera itself may "hang" or "crash," the sensors and switches can go offline or provide invalid/incorrect readings, etc. The failure modes are too many, and the limitations of plugin operation on Vera too varied, to provide a "fail safe" plugin. For this reason, AVT is appropriate for use only in attended operation, when competent adult humans can detect and mitigate any problems with the Vera, devices, plugin, configuration, or environment that could lead to undesired operation or a hazardous condition. By running AVT, you agree that you understand the appurtenant risks inherent with running it 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, then you may not and must not use AVT. AVT is offered under GPL 3.0; see the LICENSE file on the AutoVirtualThermostat GitHub Repository for additional details and licensing information.