Interface Library for Venstar ColorTouch Thermostat API v5
Project description
# Python3 API for Venstar ColorTouch thermostats
The [Venstar ColorTouch thermostat](https://venstar.com/thermostats/colortouch/) is a WIFI thermostat with a REST api. This is a simple Python3 API for talking to it. The [API documents](http://developer.venstar.com/index.html) are required reading.
## Limitations
The API does not implement the Venstar discovery protocol. It is assumed that you know the IP address or FQDN of your thermostat(s).
## Testing
```bash
$ python venstarcolortouch 192.168.1.252
Testing with IP: 192.168.1.252
Login successful. API: 5 Type: residential
Was able to get info:{u'spacetemp': 67.0, u'schedulepart': 255, u'dehum_setpoint': 0, u'away': 0, u'cooltempmax': 99.0, u'cooltemp': 78.0, u'tempunits': 0, u'state': 1, u'schedule': 0, u'hum': 0, u'heattemp': 75.0, u'hum_setpoint': 36, u'fan': 0, u'hum_active': 99, u'heattempmax': 99.0, u'cooltempmin': 35.0, u'name': u'DebtRidge', u'mode': 1, u'heattempmin': 35.0, u'availablemodes': 0, u'fanstate': 1, u'setpointdelta': 2.0}
Name is MyHouse
Fan is 0
Heat setpoint is 75.0
Cool setpoint is 78.0
Was able to get sensors:{u'sensors': [{u'hum': 36, u'name': u'Thermostat', u'temp': 67.0}, {u'name': u'Outdoor', u'temp': 0.0}]}
Indoor temp is 67.0 and humidity is 36
Runtimes: {u'cool1': 0, u'cool2': 0, u'ts': 1429574400, u'fc': 0, u'heat2': 0, u'heat1': 0, u'aux2': 0, u'aux1': 0}
Path is: /control
set_control Success!
Heat setpoint is 60.0
Cool setpoint is 90.0
Path is: /control
set_control Success!
Heat setpoint is 75.0
Cool setpoint is 78.0
```
## Usage
```Python
class VenstarColorTouch:
def __init__(self, addr, timeout):
```
Class instantiation requires an IP address or hostname with an optional timeout.
```Python
ct = venstarcolortouch.VenstarColorTouch(a, timeout=5)
if ct.login() is True:
print("Login successful. API: {0} Type: {1}".format(ct._api_ver,ct._type))
```
The login() function does not really log in, but it does confirm communication and that the API version is recent enough.
## API
API calls use the following constants:
```Python
MODE_OFF
MODE_HEAT
MODE_COOL
MODE_AUTO
STATE_IDLE
STATE_HEATING
STATE_COOLING
STATE_LOCKOUT
STATE_ERROR
FAN_AUTO
FAN_ON
FANSTATE_OFF
FANSTATE_ON
TEMPUNITS_F
TEMPUNITS_C
SCHED_F
SCHED_C
SCHEDPART_MORNING
SCHEDPART_DAY
SCHEDPART_EVENING
SCHEDPART_NIGHT
SCHEDPART_INACTIVE
AWAY_HOME
AWAY_AWAY
```
### Functions
There are ```update_*``` functions which update local copies of various pieces of data. Then there are ```get_*``` functions for retrieving that data and finally ```set_*``` functions for changing writable settings.
* ```update_sensors()``` - Update the state of indoor and outdoor temperature sensors.
* ```get_runtimes()``` - Gather runtime data.
* ```get_info()``` - returns a dict of information.
<pre>
{u'spacetemp',
u'schedulepart',
u'dehum_setpoint',
u'away',
u'cooltempmax',
u'cooltemp',
u'tempunits',
u'state',
u'schedule',
u'hum',
u'heattemp',
u'hum_setpoint',
u'fan',
u'hum_active',
u'heattempmax',
u'cooltempmin',
u'name',
u'mode',
u'heattempmin',
u'availablemodes',
u'fanstate',
u'setpointdelta'}
</pre>
```python
get_info("heattemp")
```
* ```get_thermostat_sensor(attr)``` Get a specific thermostat sensor's value.
```python
get_thermostat_sensor("temp")
```
* ```get_outdoor_sensor(attr)``` Get an outdoor sensor's value.
```python
get_outdoor_sensor("temp")```
* ```get_alerts()``` Get any alerts that are registered.
* ```set_setpoints(heattemp, cooltemp)``` Set heattemp/cooltemp.
* ```set_mode(mode)``` Set the thermostat mode.
* MODE_OFF
* MODE_HEAT
* MODE_COOL
* MODE_AUTO
* ```set_fan(fan)``` Set the Fan mode.
* FAN_AUTO
* FAN_ON
* ```set_tempunits(tempunits)``` Set degrees to either Celsius or Fahrenheit
* TEMPUNITS_F
* TEMPUNITS_C
* ```set_away(away)``` Set either Home or Away schedule.
* AWAY_HOME
* AWAY_AWAY
* ```set_schedule(schedule)``` Set Schedule On or Off.
* 0 - off
* 1 - on
* ```set_hum_setpoint(hum_setpoint)``` Set humidifier Setpoint
* ```set_dehum_setpoint(dehum_setpoint)``` Set dehumidifier Setpoint
The [Venstar ColorTouch thermostat](https://venstar.com/thermostats/colortouch/) is a WIFI thermostat with a REST api. This is a simple Python3 API for talking to it. The [API documents](http://developer.venstar.com/index.html) are required reading.
## Limitations
The API does not implement the Venstar discovery protocol. It is assumed that you know the IP address or FQDN of your thermostat(s).
## Testing
```bash
$ python venstarcolortouch 192.168.1.252
Testing with IP: 192.168.1.252
Login successful. API: 5 Type: residential
Was able to get info:{u'spacetemp': 67.0, u'schedulepart': 255, u'dehum_setpoint': 0, u'away': 0, u'cooltempmax': 99.0, u'cooltemp': 78.0, u'tempunits': 0, u'state': 1, u'schedule': 0, u'hum': 0, u'heattemp': 75.0, u'hum_setpoint': 36, u'fan': 0, u'hum_active': 99, u'heattempmax': 99.0, u'cooltempmin': 35.0, u'name': u'DebtRidge', u'mode': 1, u'heattempmin': 35.0, u'availablemodes': 0, u'fanstate': 1, u'setpointdelta': 2.0}
Name is MyHouse
Fan is 0
Heat setpoint is 75.0
Cool setpoint is 78.0
Was able to get sensors:{u'sensors': [{u'hum': 36, u'name': u'Thermostat', u'temp': 67.0}, {u'name': u'Outdoor', u'temp': 0.0}]}
Indoor temp is 67.0 and humidity is 36
Runtimes: {u'cool1': 0, u'cool2': 0, u'ts': 1429574400, u'fc': 0, u'heat2': 0, u'heat1': 0, u'aux2': 0, u'aux1': 0}
Path is: /control
set_control Success!
Heat setpoint is 60.0
Cool setpoint is 90.0
Path is: /control
set_control Success!
Heat setpoint is 75.0
Cool setpoint is 78.0
```
## Usage
```Python
class VenstarColorTouch:
def __init__(self, addr, timeout):
```
Class instantiation requires an IP address or hostname with an optional timeout.
```Python
ct = venstarcolortouch.VenstarColorTouch(a, timeout=5)
if ct.login() is True:
print("Login successful. API: {0} Type: {1}".format(ct._api_ver,ct._type))
```
The login() function does not really log in, but it does confirm communication and that the API version is recent enough.
## API
API calls use the following constants:
```Python
MODE_OFF
MODE_HEAT
MODE_COOL
MODE_AUTO
STATE_IDLE
STATE_HEATING
STATE_COOLING
STATE_LOCKOUT
STATE_ERROR
FAN_AUTO
FAN_ON
FANSTATE_OFF
FANSTATE_ON
TEMPUNITS_F
TEMPUNITS_C
SCHED_F
SCHED_C
SCHEDPART_MORNING
SCHEDPART_DAY
SCHEDPART_EVENING
SCHEDPART_NIGHT
SCHEDPART_INACTIVE
AWAY_HOME
AWAY_AWAY
```
### Functions
There are ```update_*``` functions which update local copies of various pieces of data. Then there are ```get_*``` functions for retrieving that data and finally ```set_*``` functions for changing writable settings.
* ```update_sensors()``` - Update the state of indoor and outdoor temperature sensors.
* ```get_runtimes()``` - Gather runtime data.
* ```get_info()``` - returns a dict of information.
<pre>
{u'spacetemp',
u'schedulepart',
u'dehum_setpoint',
u'away',
u'cooltempmax',
u'cooltemp',
u'tempunits',
u'state',
u'schedule',
u'hum',
u'heattemp',
u'hum_setpoint',
u'fan',
u'hum_active',
u'heattempmax',
u'cooltempmin',
u'name',
u'mode',
u'heattempmin',
u'availablemodes',
u'fanstate',
u'setpointdelta'}
</pre>
```python
get_info("heattemp")
```
* ```get_thermostat_sensor(attr)``` Get a specific thermostat sensor's value.
```python
get_thermostat_sensor("temp")
```
* ```get_outdoor_sensor(attr)``` Get an outdoor sensor's value.
```python
get_outdoor_sensor("temp")```
* ```get_alerts()``` Get any alerts that are registered.
* ```set_setpoints(heattemp, cooltemp)``` Set heattemp/cooltemp.
* ```set_mode(mode)``` Set the thermostat mode.
* MODE_OFF
* MODE_HEAT
* MODE_COOL
* MODE_AUTO
* ```set_fan(fan)``` Set the Fan mode.
* FAN_AUTO
* FAN_ON
* ```set_tempunits(tempunits)``` Set degrees to either Celsius or Fahrenheit
* TEMPUNITS_F
* TEMPUNITS_C
* ```set_away(away)``` Set either Home or Away schedule.
* AWAY_HOME
* AWAY_AWAY
* ```set_schedule(schedule)``` Set Schedule On or Off.
* 0 - off
* 1 - on
* ```set_hum_setpoint(hum_setpoint)``` Set humidifier Setpoint
* ```set_dehum_setpoint(dehum_setpoint)``` Set dehumidifier Setpoint
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
venstarcolortouch-0.4.tar.gz
(7.8 kB
view hashes)
Built Distribution
Close
Hashes for venstarcolortouch-0.4-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8f19ef5eab66e2d77b32717dd6cc266e504bdcaf97903db84a460caab2831040 |
|
MD5 | 00d974474568ce0a9bfb3a7342f8fa48 |
|
BLAKE2b-256 | c3c08ab00e462f26d1f6b016b47479530bed32acde013692ab67fbff68ca5e1d |