Python3 API for Venstar ColorTouch thermostats

The Venstar ColorTouch thermostat is a WIFI thermostat with a REST api. This is a simple Python3 API for talking to it. The API documents 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

$ 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

class VenstarColorTouch:
    def __init__(self, addr, timeout):

Class instantiation requires an IP address or hostname with an optional timeout.

    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:

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
SECURITY_OFF
SECURITY_ON
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_info() - Update the control state of the thermostat. Must be called at least once before any set_ functions.

• update_sensors() - Update the state of indoor and outdoor temperature sensors.

• get_runtimes() - Gather runtime data.

• get_info() - returns a dict of information.

    {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'}
    

  get_info("heattemp")

• get_sensor(name, attr) Get a specific named sensor's value. In case of duplicate names, the first matching sensor will be returned.

  get_sensor("Outdoor", "temp")

• get_sensor_list(type) Get a list of sensor names, optionally filtered by type. Type is one of "Control", "Local", "Outdoor", "Remote", "Return", or "Supply".

  get_sensor_list()
  get_sensor_list("Remote")

• get_thermostat_sensor(attr) Get a specific thermostat sensor's value.

  get_thermostat_sensor("temp")

• get_outdoor_sensor(attr) Get an outdoor sensor's value.

  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

T2100 Specific

• set_security(security) Set the Security mode (whether or not setpoint limits are active).
  • SECURITY_OFF
  • SECURITY_ON
• set_setpoint_limits(sp_max, sp_min) Set the maximum and minimum setpoint limits.