<br />

# ThermostatTemperatureSetpoint Schema

[Nest Thermostat](https://developers.google.com/nest/device-access/api/thermostat)

`sdm.devices.traits.ThermostatTemperatureSetpoint`

This trait belongs to device types of THERMOSTAT that support setting target temperature and temperature range.

<br />

## Fields

<br />

<br />

> [!NOTE]
> **Note:** A GET request for this trait only returns the current mode's temperature value(s).

<br />

| Field | Description | Data Type |
|---|---|---|
| `heatCelsius` | Target temperature in Celsius for thermostat HEAT and HEATCOOL modes. | `number` Example: 20.0 |
| `coolCelsius` | Target temperature in Celsius for thermostat COOL and HEATCOOL modes. | `number` Example: 22.0 |

<br />

<br />

#### Sample GET request and response - HEAT

### Request

```
GET /enterprises/project-id/devices/device-id
```

### Response

    {
      "name" : "enterprises/project-id/devices/device-id",
      "traits" : {
        "sdm.devices.traits.ThermostatTemperatureSetpoint" : {
          "heatCelsius" : 20.0,
        }
      }
    }

<br />

<br />

#### Sample GET request and response - COOL

### Request

```
GET /enterprises/project-id/devices/device-id
```

### Response

    {
      "name" : "enterprises/project-id/devices/device-id",
      "traits" : {
        "sdm.devices.traits.ThermostatTemperatureSetpoint" : {
          "coolCelsius" : 22.0
        }
      }
    }

<br />

<br />

#### Sample GET request and response - HEATCOOL

### Request

```
GET /enterprises/project-id/devices/device-id
```

### Response

    {
      "name" : "enterprises/project-id/devices/device-id",
      "traits" : {
        "sdm.devices.traits.ThermostatTemperatureSetpoint" : {
          "heatCelsius" : 20.0,
          "coolCelsius" : 22.0
        }
      }
    }

<br />

## Commands

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](https://developers.google.com/nest/device-access/traits/device/thermostat-temperature-setpoint#setheat) | `heatCelsius` |
| COOL | [SetCool](https://developers.google.com/nest/device-access/traits/device/thermostat-temperature-setpoint#setcool) | `coolCelsius` |
| HEATCOOL | [SetRange](https://developers.google.com/nest/device-access/traits/device/thermostat-temperature-setpoint#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.

> [!CAUTION]
> All Set\* commands will be rejected if the thermostat is in Eco mode. See the [ThermostatEco](https://developers.google.com/nest/device-access/traits/device/thermostat-eco) trait for more information.

<br />

### SetHeat

Sets the target temperature when the thermostat is in HEAT mode.

#### SetHeat request and response

### Request

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

### Response

```
{}
```

#### SetHeat request fields

| Field | Description | Data Type |
|---|---|---|
| `heatCelsius` | The target temperature to set when the thermostat is in HEAT mode. | `number` Example: 22.0 |

### SetCool

Sets the target temperature when the thermostat is in COOL mode.

#### SetCool request and response

### Request

    POST /enterprises/project-id/devices/device-id:executeCommand
    {
      "command" : "sdm.devices.commands.ThermostatTemperatureSetpoint.SetCool",
      "params" : {
        "coolCelsius" : 20.0
      }
    }

### Response

```
{}
```

#### SetCool request fields

| Field | Description | Data Type |
|---|---|---|
| `coolCelsius` | The target temperature to set when the thermostat is in COOL mode. | `number` Example: 20.0 |

### SetRange

Sets the minimum and maximum temperatures when the thermostat is in HEATCOOL mode.

#### SetRange request and response

### Request

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

### Response

```
{}
```

#### SetRange request fields

| Field | Description | Data Type |
|---|---|---|
| `heatCelsius` | The minimum target temperature to set when the thermostat is in HEATCOOL mode. | `number` Example: 20.0 |
| `coolCelsius` | The maximum target temperature to set when the thermostat is in HEATCOOL mode. | `number` Example: 22.0 |

<br />


## Errors

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

| Error Message | RPC | Troubleshooting |
|---|---|---|
| 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](https://developers.google.com/nest/device-access/traits/device/thermostat-mode) trait. The thermostat mode must be changed to HEAT, COOL, or HEATCOOL prior to changing the Eco mode. |
| 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 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](https://developers.google.com/nest/device-access/reference/errors/api) for
the full list of API error codes.

<br />