Simple Service Discovery Protocol

The Simple Service Discovery Protocol (SSDP) is a network protocol based on the Internet Protocol Suite for advertisement and discovery of network services and presence information. It accomplishes this without assistance of server-based configuration mechanisms, such as the Dynamic Host Configuration Protocol (DHCP) or the Domain Name System (DNS), and without special static configuration of a network host. SSDP is the basis of the discovery protocol of Universal Plug and Play and is intended for use in residential or small office environments.

SSDP is a text-based protocol based on HTTPU. It uses the User Datagram Protocol (UDP) as the underlying transport protocol. Services are announced by the hosting system with multicast addressing to a specifically designated IP multicast address 239.255.255.250 at UDP port number 1900.

Location header is the URL for the Venstar Thermostat Local API service. The thermostat name is contained in the USN header. If you have multiple Venstar thermostats on your network, your application can receive multiple packets with different locations and names.

At a regular interval Venstar thermostats broadcast their services by sending a NOTIFY message similar to the response message above to the multicast address and port. NOTIFY messages replace the ST header with NT. If your application has not received a new NOTIFY message before the Cache-Control expires, Venstar thermostat is no longer available on the network.

API Information

Query general information

This request returns a list of settings needed to render the home screen of a thermostat.

GET /query/info

Example:

http://192.168.1.100/query/info

Response:

{

name: 'Office',
mode: 0,
state: 0,
activestage: 1,
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,
hum: 50,
hum_setpoint: 0,
dehum_setpoint: 99,
hum_active: 0,
availablemodes: 0

}

VIEW RESPONSE DEFINITIONS

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
activestage	Current demand stage. Values from 0 to 4. “0” means that there is no active heating or cooling at the moment.
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: Disabled 1: Enabled
schedulepart	Current schedule part 0: occupied 1 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
hum_setpoint	Humidify setpoint
dehum_setpoint	Dehumidify setpoint
hum_active	Humidifier active 0: Off 1: On
availablemodes	Available thermostat modes 0: all modes 1: heat/cool only 2: heat only 3: cool only

Query sensors

This request returns a list of all the thermostat's sensors.

GET /query/sensors

Example:

http://192.168.1.100/query/sensors

Response:

{

sensors: [

{

name: 'Thermostat',
temp: 77
hum: 40
intensity: 3
iaq: 39.71
co2: 558.83

},
{

name: 'Outdoor',
temp: 0

},
{

name: 'SENSOR0729',
temp: 64
battery: 100
type: 'Remote'

}

]

}

VIEW RESPONSE DEFINITIONS

VALUE	DEFINITION
name	Sensor name
temp	Sensor temperature
hum	Humidity sensor if available
intensity	Relative light level. Values from 1 to 254
iaq	Current indoor air quality index. 0-50 - Excellent, 51-100 - Good, 101-250 - Moderate, > 250 - Poor
co2	Current CO2 estimate in ppm
battery	Sensor battery level in %
type	Sensor type if available. Valid values are: "Outdoor", "Return", "Remote", "Supply"

Query runtimes

This request returns the runtime data of a thermostat.

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

}

]

}

VIEW RESPONSE DEFINITIONS

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 a thermostat.

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

}

]

}

VIEW RESPONSE DEFINITIONS

VALUE	DEFINITION
name	Alert name
active	If the alert is active

Control

This request enables remote control of a Venstar thermostat 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

VIEW REQUEST DEFINITIONS

VALUE	DEFINITION
mode	0: Off 1: Heat 2: Cool 3: Auto
fan	0: Auto 1: On
heattemp	Heat to temperature
cooltemp	Cool to temperature

Control request requirements

All control calls with mode must include heattemp and cooltemp parameters in tempunits from '/query/info'. 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 a Venstar thermostat 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

VIEW REQUEST DEFINITIONS

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%

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: 17

{'error':true}

Error Handling