API Documentation


The Remote Control Service is a simple RESTful service available at a HTTP location and port advertised by the SSDP protocol. The following API documentation covers all the available REST calls. The Communication body structure is standardized on JavaScript Object Notation (JSON).


API Information

This request returns the current API version and the type of ColorTouch thermostat. Thermostat type is either residential or commercial. This command is accessed via an HTTP GET.

GET /

Example:

http://192.168.1.100/

Response
{
 "api_ver": 3,
 "type": "residential"
}										

Query

This request returns a list of settings needed to render the home screen of ColorTouch thermostat. This command is accessed via an HTTP GET.

GET /query/info

Example:

http://192.168.1.100/query/info

Response
{
    "name": "Office",
    "mode": 0,
    "state": 0,
    "fan": 0,
    "fanstate": 0,
    "tempunits": 0,
    "schedule": 0,
    "schedulepart": 0,
    "away": 0,
    "holiday": 0,
    "override": 0,
    "overridetime": 0,
    "forceunocc": 0,
    "spacetemp": 79,
    "heattemp": 78,
    "cooltemp": 75,
    "cooltempmin": 35,
    "cooltempmax": 99,
    "heattempmin": 35,
    "heattempmax": 99,
    "setpointdelta": 2,
    "availablemodes": 0
}

Value Definition
mode

Current thermostat mode

0: Off
1: Heat
2: Cool
3: Auto
state

Current thermostat state

0: Idle
1: Heating
2: Cooling
3: Lockout
4: Error

fan

Current fan setting

0: Auto
1: On

fanstate

Current fan state

0: Off
1: On

tempunits

Current temperature units

0: Fahrenheit
1: Celsius

schedule

Current schedule state

0: Fahrenheit
1: Celsius

schedulepart

Current schedule part

0: occupied1 or morning
1: occupied2 or day
2: occupied3 or evening
3: unoccupied or night
255: inactive

away (residential only)

Current away state

0: Home
1: Away

holiday (commercial only)

Current holiday state

0: not observing holiday
1: observing holiday

override (commercial only)

Current override state

0: off
1: on

overridetime (commercial only)

Time left in override

0 to 240 minutes

forceunocc (commercial only)

Current forceunocc state

0: off
1: on

spacetemp

Current space temperature

heattemp

Current heat to temperature

cooltemp

Current cool to temperature

cooltempmin

Minimum cool to temperature

cooltempmax

Maximum cool to temperature

heattempmin

Minimum heat to temperature

heattempmax

Maximum heat to temperature

setpointdelta

Minimum temperature difference of heat and cool temperatures

hum

Current humidity, if available

availablemodes

Available thermostat modes

0: all modes
1: heat/cool only
2: heat only
3: cool only


Query / Sensors

This request returns a list (array) of all the thermostat's sensors via an HTTP GET.

GET /query/sensors

Example:

http://192.168.1.100/query/sensors

Response
{
   "sensors": [
       {
           "name": "Thermostat",
	   "temp": 77
       },
       {
           "name": "Outdoor",
           "temp": 0
       }
   ]
}
									  

Value Definition
name

Sensor name

temp

Sensor temperature

hum

Humidity sensor if available


Query / Runtimes

This request returns the runtime data reports of the ColorTouch thermostat. This command is accessed via an HTTP GET.

GET /query/runtimes

Example:

http://192.168.1.100/query/runtimes

Response
{
    "runtimes": [
        {
            "ts": 2147483647,
            "heat1": 0,
            "heat2": 0,
            "cool1": 0,
            "cool2": 0,
            "aux1": 0,
            "aux2": 0,
            "fc": 0
        },
        {
            "ts": 2147483647,
            "heat1": 0,
            "heat2": 0,
            "cool1": 0,
            "cool2": 0,
            "aux1": 0,
            "aux2": 0,
            "ov": 0
        },
    ]
}
									  

Value Definition
ts

Timestamp

heat1

Stage 1 Heat runtime in minutes

heat2

Stage 2 Heat runtime in minutes

cool1

Stage 1 Cool runtime in minutes

cool2

Stage 2 Cool runtime in minutes

aux1

Stage 1 Auxiliary runtime in minutes

aux2

Stage 2 Auxiliary runtime in minutes

fc (residential only)

Free Cooling runtime in minutes

ov (commercial only)

Override runtime in minutes


Query / Alerts

This request returns a list of alert states for the ColorTouch thermostat. This command is accessed via an HTTP GET.

GET /query/alerts

Example:

http://192.168.1.100/query/alerts

Response
{
    "alerts": [
        {
            "name": "Air Filter",
            "active": false
        },
        {
            "name": "UV Lamp",
            "active": false
        },
        {
            "name": "Service",
            "active": false
        }
    ]
}
									  

Value Definition
name

Alert name

active

If the alert is active


Control

This request enables remote control of ColorTouch over the network. This command is submitted via an HTTP POST and is URL encoded instead of JSON.

POST /control

Example Request:

POST /control HTTP/1.1
Content-Type: application/x-www-form-urlencoded
mode=0&fan=0&heattemp=70&cooltemp=75
											

Control request requirements

All control calls with mode must include heattemp and cooltemp parameters. When setting mode to Auto, cooltemp must be greater than heattemp and the setpointdelta from "/query/info" needs to be respected. A security PIN is required when Screenlock settings are enabled.

Success Response
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 17
{"success":true}
Error Response
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 14
{"error":true}

Settings

This request enables changing settings of ColorTouch over the network. This command is submitted via an HTTP POST and is URL encoded instead of JSON.

Settings request requirements

A security PIN is required when Screenlock settings are enabled.

POST /settings

Example Request:

POST /settings HTTP/1.1
Content-Type: application/x-www-form-urlencoded
tempunits=0&away=0&schedule=0&hum_setpoint=0&dehum_setpoint=0
											

Success Response
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 17
{"success":true}
Error Response
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 14
{"error":true}

Value Definition
tempunits

Set thermostat temperature units

0: Fahrenheit
1: Celsius

away (residential only)

Set away state

0: home
1: away

schedule

Set schedule state

0: off
1: on

hum_setpoint

Humidify Setpoint

0% - 60%

dehum_setpoint

Dehumidify Setpoint

25% - 99%


Error Handling

All the requests in this section returns the described JSON objects if the action was performed without an error. If the request was unsuccessful, the response object is described below.

POST /settings
Error Response
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 39
{"error":true, "reason":"error reason"}