Thermostat

All Google Nest Thermostat models are supported in the Smart Device Management (SDM) API. These devices return the THERMOSTAT device type:

sdm.devices.types.THERMOSTAT

Traits

Reference

The following traits, commands, or events are related to this group:

Trait	Description	Commands
Connectivity	This trait belongs to any device that has connectivity information.
Fan	This trait belongs to any device that has the system ability to control the fan.	SetTimer
Humidity	This trait belongs to any device that has a sensor to measure humidity.
Info	This trait belongs to any device for device-related information.
Settings	This trait belongs to any device for device-related settings information.
Temperature	This trait belongs to any device that has a sensor to measure temperature.
ThermostatEco	This trait belongs to device types of THERMOSTAT that support ECO modes.	SetMode
ThermostatHvac	This trait belongs to device types of THERMOSTAT that can report HVAC details.
ThermostatMode	This trait belongs to device types of THERMOSTAT that support different thermostat modes.	SetMode
ThermostatTemperatureSetpoint	This trait belongs to device types of THERMOSTAT that support setting target temperature and temperature range.	SetHeat SetCool SetRange

JSON

The absence of a trait in a GET response indicates that the trait or feature is not currently available for the device. See Device types for more information.

{
  "type" : "sdm.devices.types.THERMOSTAT",
  "traits" : {
    "sdm.devices.traits.Connectivity" : {
      "status" : "ONLINE"
    },
    "sdm.devices.traits.Fan" : {
      "timerMode" : "ON",
      "timerTimeout" : "2019-05-10T03:22:54Z"
    },
    "sdm.devices.traits.Humidity" : {
      "ambientHumidityPercent" : 35.0
    },
    "sdm.devices.traits.Info" : {
      "customName" : "My device"
    },
    "sdm.devices.traits.Settings" : {
      "temperatureScale" : "CELSIUS"
    },
    "sdm.devices.traits.Temperature" : {
      "ambientTemperatureCelsius" : 23.0
    },
    "sdm.devices.traits.ThermostatEco" : {
      "availableModes" : ["MANUAL_ECO", "OFF"],
      "mode" : "MANUAL_ECO",
      "heatCelsius" : 20.0,
      "coolCelsius" : 22.0
    },
    "sdm.devices.traits.ThermostatHvac" : {
      "status" : "HEATING"
    },
    "sdm.devices.traits.ThermostatMode" : {
      "availableModes" : ["HEAT", "COOL", "HEATCOOL", "OFF"],
      "mode" : "COOL"
    },
    "sdm.devices.traits.ThermostatTemperatureSetpoint" : {
      "heatCelsius" : 20.0,
      "coolCelsius" : 22.0
    }
  }
}

Temperature and humidity

To read the thermostat's ambient temperature, use the Temperature trait. The ambient temperature is measured at the device.

To read the thermostat's ambient humidity, use the Humidity trait. The ambient humidity is measured at the device.

Temperature scale

The Google Nest Thermostat can display temperature in either degrees Celsius or Fahrenheit, but the scale cannot be set by the SDM API. To determine the temperature scale currently set by the user, use the Settings trait.

Change the mode

The thermostat's mode is managed by two different traits: ThermostatMode and ThermostatEco.

Standard modes

To change the thermostat mode to HEAT, COOL, or HEATCOOL, use the SetMode command of the ThermostatMode trait.

This command can also be used to turn the thermostat's mode to OFF. It cannot be used to turn on Eco mode.

For example, to change one of the standard thermostat modes:

Request

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.ThermostatMode.SetMode",
  "params" : {
    "mode" : "HEAT"
  }
}

Response

{}

Eco mode

To turn Eco mode on, use MANUAL_ECO as the mode with the SetMode command of the ThermostatEco trait:

Request

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.ThermostatEco.SetMode",
  "params" : {
    "mode" : "MANUAL_ECO"
  }
}

Response

{}

This command impacts other traits, based on the current status of, or changes to, the Eco mode:

If Eco mode is OFF, the thermostat mode will default to the last standard mode (HEAT, COOL, HEATCOOL, or OFF) that was active.
If Eco mode is MANUAL_ECO:

Commands for the ThermostatTemperatureSetpoint trait are rejected.
Temperature setpoints are not returned by the ThermostatTemperatureSetpoint trait.

Change the temperature setpoints

Temperature setpoints can only be changed when the thermostat is in HEAT, COOL, or HEATCOOL modes, and the setpoints allowed correspond to the thermostat's current mode. Temperature setpoints cannot be changed when the mode is OFF or when the Eco mode is set to MANUAL_ECO.

The thermostat must be in the mode that corresponds to the command being called prior to changing the temperature setpoints. The command and field(s) to change the setpoint(s) varies by thermostat mode.

For example, to issue the SetHeat command, the thermostat must be in HEAT mode first:

Mode	Command	Field(s)
HEAT	SetHeat	`heatCelsius`
COOL	SetCool	`coolCelsius`
HEATCOOL	SetRange	`heatCelsius`, `coolCelsius`

Note that the setpoint commands only take degrees in Celsius as a parameter, though the Google Nest Thermostat can display temperature in either degrees Celsius or Fahrenheit.

For example, to change the temperature setpoint when the thermostat is in HEAT mode, use the SetHeat command of the ThermostatTemperatureSetpoint trait:

Request

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.ThermostatTemperatureSetpoint.SetHeat",
  "params" : {
    "heatCelsius" : 22.0
  }
}

Response

{}

Eco mode setpoints

The heatCelsius and coolCelsius setpoints returned by the ThermostatEco trait are set by the user, and cannot be changed through the SDM API.

Turn the fan on or off

If the thermostat supports a fan, use the SetTimer command of the Fan trait to turn it on or off. When turning on, you can specify the length of time you want the fan to run, in seconds.

For example, to run the fan for an hour:

Request

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.Fan.SetTimer",
  "params" : {
    "timerMode" : "ON",
    "duration" : "3600s"
  }
}

Response

{}

If the duration field is omitted, the fan will run for a default time of 15 minutes.

Check device connectivity

If the device is not responding to commands or sending events, or you receive errors from the API related to the device, use the Connectivity trait to check the device's connectivity for an OFFLINE status. Check the device's connection to the internet and make sure the Nest Service is up.

If you have events enabled, you should also have received a resource event indicating that the device has gone offline:

Payload

{
  "eventId" : "e9e07553-29c7-4556-90f1-fe27921969b9",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "traits" : {
      "sdm.devices.traits.Connectivity" : {
        "status" : "OFFLINE"
      }
    }
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

React to device events

Any change to a trait field generates an event. For example, you would receive the following resourceUpdate event if the thermostat's HVAC status changed to HEATING:

Payload

{
  "eventId" : "4cb011b5-3756-4e51-ba22-43cdff4d9195",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "traits" : {
      "sdm.devices.traits.ThermostatHvac" : {
        "status" : "HEATING"
      }
    }
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Events are triggered for all traits associated with this device type. Enable events if you need to react to them in some way as part of an integration.

Timing of events

Note that an event for a change in HVAC status may not be delivered at the same time as events for a thermostat mode change.

For example, sometimes there is a delay in starting a thermostat's heating or cooling mode in order to protect the HVAC system. In this scenario, changing the thermostat mode may only initially send events for ThermostatMode and ThermostatTemperatureSetpoint trait changes, with the ThermostatHvac trait change sent later as a separate event once the system actually turns on. If there was no delay in turning on the HVAC system, all three events would be sent at the same time.

Errors

The following error code(s) may be returned in relation to this device:

Error Message	RPC	Troubleshooting
Cool value must be greater than heat value.	`INVALID_ARGUMENT`	Make sure that the `heatCelsius` field is less than the `coolCelsius` field in your command.
Command not allowed in current thermostat mode.	`FAILED_PRECONDITION`	Some thermostat models do not support changing the Eco mode when the thermostat mode is OFF, according to the ThermostatMode trait. The thermostat mode must be changed to HEAT, COOL, or HEATCOOL prior to changing the Eco mode.
Thermostat fan unavailable.	`FAILED_PRECONDITION`	The thermostat does not have a fan capability. Fan-related traits and commands cannot be used for this device.
Command not allowed when thermostat in MANUAL_ECO mode.	`FAILED_PRECONDITION`	The temperature setpoint cannot be set when the thermostat is in manual Eco mode.

See the API Error Code Reference for the full list of API error codes.