Ask or search…
βŒƒK
Links

Setting the Current HVAC and Fan Mode Settings

Learn how to configure the current climate settings on a thermostat.
Seam enables you to adjust the current heating and cooling settings on a smart thermostat, including the HVAC mode and its corresponding set points. It also enables you to configure the fan mode. This guide explains how to use the Seam API to perform these actions.
When you send a command to change a setting on a thermostat, it might take a while for Seam to confirm the success of the action. To handle this potential delay, Seam provides an action attempt object that tracks the status of the action, indicating whether the action was successful.
To ensure that the action has executed successfully, poll the status of the action attempt object using the Get Action Attempt request. Once Seam has successfully adjusted the thermostat setting, the status of the action attempt indicates success.

Current Climate Setting

The set of current heating, ventilation, and air conditioning (HVAC) settings on a thermostat includes the following:
To set the HVAC mode and set points, issue a thermostat heat, cool, heat_cool, or off request and include the desired set points in the body of the request. When you issue one of these commands, Seam sets the hvac_mode_setting accordingly.

Fan Mode

The fan mode includes the following options:
  • on: The fan continuously operates, ensuring air circulation, regardless of the heating or cooling demand.
  • auto: The fan activates only when heating or cooling is on, making this setting a more energy-efficient choice.
Seam supports a single ongoing fan mode setting.

Before You Begin

To confirm that Seam supports thermostat programming for your device, use Get Device or Get Thermostat to query the device and check its capabilities_supported property. Ensure that the capabilities_supported list includes thermostat. For more information, see Retrieving Individual Thermostats.

Process Overview

To configure and then verify a climate setting on a thermostat, perform the following steps:

1. Execute the Climate Setting Request

Issue one of the following requests:
Climate Setting Request
Description
​Heat​
Set the thermostat to heat mode.
​Cool​
Set the thermostat to cool mode.
​Heat-Cool​
Set the thermostat to dual heat-cool (auto) mode.
​Off​
Turn off the thermostat.
​Fan Mode​
Set the fan mode to on or off.
The Seam API returns an action attempt (action_attempt object) that monitors the status of the action.
The following example issues a request to set a specific thermostat to heat mode with a heating set point of 20Β° C:
Python
cURL (bash)
JavaScript
PHP
Java
Go
Request:
heat_request = seam.thermostats.heat(
device = "518f692b-f865-4590-8c3e-3849e9984c75",
heating_set_point_celsius = 20
)
​
pprint(heat_request)
Response:
ActionAttempt(action_attempt_id='97125745-15d9-4970-b5be-c34ec3ce1c81',
action_type='SET_HEAT',
status='success',
result={},
error=None)
Request:
curl -X 'POST' \
'https://connect.getseam.com/thermostats/heat' \
-H 'accept: application/json' \
-H 'Authorization: Bearer ${API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"device_id": "518f692b-f865-4590-8c3e-3849e9984c75",
"heating_set_point_celsius": 20
}'
Response:
{
"action_attempt": {
"status": "pending",
"action_type": "SET_HEAT",
"action_attempt_id": "7f7f6e18-2c50-46bb-9ace-f52d05069db4",
"result": null,
"error": null
},
"ok": true
}
Request:
const heat_request = await seam.thermostats.heat({
device_id: "518f692b-f865-4590-8c3e-3849e9984c75",
heating_set_point_celsius: 20
})
​
console.log(heat_request)
Response:
{
actionAttempt: {
status: 'success',
action_attempt_id: '38c06dba-99b1-4c10-b542-f98e2963cb52',
action_type: 'SET_HEAT',
result: {},
error: null
}
}
Request:
$heat_request = $seam->thermostats->heat(
device_id: "5ce2cd35-09b1-458c-bb08-51ee83c35be7",
heating_set_point_celsius: 20
);
Response:
None
Request:
var deviceId = "518f692b-f865-4590-8c3e-3849e9984c75";
seam.thermostats().heat(ThermostatsHeatRequest.builder()
.deviceId(deviceId)
.heatingSetPointCelsius(20.0)
.build());
Device thermostat = seam.thermostats()
.get(ThermostatsGetRequest.builder()
.deviceId(deviceId)
.build());
System.out.println("Thermostat ID: " + thermostat.getDeviceId());
System.out.println("Mode: " + thermostat.getProperties().getCurrentClimateSetting().get().getHvacModeSetting());
System.out.println("Heating set point (Celsius): " +
thermostat.getProperties().getCurrentClimateSetting().get().getHeatingSetPointCelsius());
Response:
Thermostat ID: 518f692b-f865-4590-8c3e-3849e9984c75
Mode: Optional[heat]
Heating set point (Celsius): Optional[20.0]
Request:
heat_request, uErr := client.Thermostats.Heat(context.Background(), &api.ThermostatsHeatRequest{
DeviceId: "5ce2cd35-09b1-458c-bb08-51ee83c35be7",
HeatingSetPointCelsius: api.Float64(20),
})
​
if uErr != nil {
return uErr
}
​
fmt.Println(heat_request)
return nil
Response:
{
"action_attempt": {
"status": "pending",
"action_type": "SET_HEAT",
"action_attempt_id": "241e79cd-4bda-499f-8e2e-d7ae01d273cf",
"result": null,
"error": null
},
"ok": true
}

2. Poll the Action Attempt to Verify the Setting Change

Use the action_attempt_id from the previous response to poll the associated action attempt using the Get Action Attempt request. When the setting modification completes successfully, the status of the action attempt changes to success.
Python
cURL (bash)
JavaScript
Java
Go
Request:
pprint(seam.action_attempts.get(action_attempt="4df7eb09-e17d-4d3a-a9c9-cfe718d3ce90"))
Response:
ActionAttempt(action_attempt_id='4df7eb09-e17d-4d3a-a9c9-cfe718d3ce90',
action_type='SET_HEAT',
status='success',
result={},
error=None)
Request:
# Use GET or POST.
curl -X 'GET' \
'https://connect.getseam.com/action_attempts/get' \
-H 'accept: application/json' \
-H 'Authorization: Bearer ${API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"action_attempt_id": "4df7eb09-e17d-4d3a-a9c9-cfe718d3ce90"
}'
Response:
{
"action_attempt": {
"status": "success",
"action_attempt_id": "4df7eb09-e17d-4d3a-a9c9-cfe718d3ce90",
"action_type": "SET_HEAT",
"result": {},
"error": null
},
"ok": true
}
Request:
console.log(await seam.actionAttempts.get("4df7eb09-e17d-4d3a-a9c9-cfe718d3ce90"))
Response:
{
status: 'success',
action_attempt_id: '4df7eb09-e17d-4d3a-a9c9-cfe718d3ce90',
action_type: 'SET_HEAT',
result: {},
error: null
}
Request:
ActionAttempt attempt = seam.actionAttempts()
.get(ActionAttemptsGetRequest.builder()
.actionAttemptId("4df7eb09-e17d-4d3a-a9c9-cfe718d3ce90")
.build());
System.out.println(attempt.isSuccess());
Response:
true
Request:
action_attempt, uErr := client.ActionAttempts.Get(context.Background(), &api.ActionAttemptsGetRequest{
ActionAttemptId: "40dc817d-9ae0-4037-9d4a-736700ee467b",
})
​
if uErr != nil {
return uErr
}
​
fmt.Println(action_attempt)
return nil
Response:
&{success {
"status": "success",
"action_attempt_id": "40dc817d-9ae0-4037-9d4a-736700ee467b",
"action_type": "SET_HEAT",
"result": {},
"error": null
} <nil> <nil>}

Set the Current HVAC and Fan Mode Settings

The following sections describe how to se the current climate settings on a thermostat:

Set a Thermostat to Heat Mode

You can set a thermostat to operate in heating mode and specify a desired heating set point temperature. By establishing the set point, the thermostat activates the associated heating system to maintain the specified temperature.
Set the HVAC mode to heat by providing the device_id of the thermostat and the heating set point in Celsius or Fahrenheit.
Python
cURL (bash)
JavaScript
PHP
Java
Go
Request:
heat_request = seam.thermostats.heat(
device = "518f692b-f865-4590-8c3e-3849e9984c75",
heating_set_point_celsius = 20
)
​
pprint(heat_request)
Response:
ActionAttempt(action_attempt_id='97125745-15d9-4970-b5be-c34ec3ce1c81',
action_type='SET_HEAT',
status='success',
result={},
error=None)
Request:
curl -X 'POST' \
'https://connect.getseam.com/thermostats/heat' \
-H 'accept: application/json' \
-H 'Authorization: Bearer ${API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"device_id": "518f692b-f865-4590-8c3e-3849e9984c75",
"heating_set_point_celsius": 20
}'
Response:
{
"action_attempt": {
"status": "pending",
"action_type": "SET_HEAT",
"action_attempt_id": "7f7f6e18-2c50-46bb-9ace-f52d05069db4",
"result": null,
"error": null
},
"ok": true
}
Request:
const heat_request = await seam.thermostats.heat({
device_id: "518f692b-f865-4590-8c3e-3849e9984c75",
heating_set_point_celsius: 20
})
​
console.log(heat_request)
Response:
{
actionAttempt: {
status: 'success',
action_attempt_id: '38c06dba-99b1-4c10-b542-f98e2963cb52',
action_type: 'SET_HEAT',
result: {},
error: null
}
}
Request:
$heat_request = $seam->thermostats->heat(
device_id: "518f692b-f865-4590-8c3e-3849e9984c75",
heating_set_point_celsius: 20
);
Response:
None
Request:
var deviceId = "518f692b-f865-4590-8c3e-3849e9984c75";
seam.thermostats().heat(ThermostatsHeatRequest.builder()
.deviceId(deviceId)
.heatingSetPointCelsius(20.0)
.build());
Device thermostat = seam.thermostats()
.get(ThermostatsGetRequest.builder()
.deviceId(deviceId)
.build());
System.out.println("Thermostat ID: " + thermostat.getDeviceId());
System.out.println("Mode: " + thermostat.getProperties().getCurrentClimateSetting().get().getHvacModeSetting());
System.out.println("Heating set point (Celsius): " +
thermostat.getProperties().getCurrentClimateSetting().get().getHeatingSetPointCelsius());
Response:
Thermostat ID: 518f692b-f865-4590-8c3e-3849e9984c75
Mode: Optional[heat]
Heating set point (Celsius): Optional[20.0]
Request:
heat_request, uErr := client.Thermostats.Heat(context.Background(), &api.ThermostatsHeatRequest{
DeviceId: "518f692b-f865-4590-8c3e-3849e9984c75",
HeatingSetPointCelsius: api.Float64(20),
})
​
if uErr != nil {
return uErr
}
​
fmt.Println(heat_request)
return nil
Response:
{
"action_attempt": {
"status": "pending",
"action_type": "SET_HEAT",
"action_attempt_id": "241e79cd-4bda-499f-8e2e-d7ae01d273cf",
"result": null,
"error": null
},
"ok": true
}

Set a Thermostat to Cool Mode

You can set a thermostat to operate in cooling mode and specify a desired cooling set point temperature. By establishing the set point, the thermostat activates the associated cooling system to maintain the specified temperature.
Set the HVAC mode to cool by providing the device_id of the thermostat and the cooling set point in Celsius or Fahrenheit.
Python
cURL (bash)
JavaScript
PHP
Java
Go
Request:
cool_request = seam.thermostats.cool(
device = "518f692b-f865-4590-8c3e-3849e9984c75",
cooling_set_point_celsius = 25
)
​
pprint(cool_request)
Response:
ActionAttempt(action_attempt_id='87478724-0e30-4fed-9f2a-456971b7b04f',
action_type='SET_COOL',
status='success',
result={},
error=None)
Request:
curl -X 'POST' \
'https://connect.getseam.com/thermostats/cool' \
-H 'accept: application/json' \
-H 'Authorization: Bearer ${API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"device_id": "518f692b-f865-4590-8c3e-3849e9984c75",
"cooling_set_point_celsius": 25
}'
Response:
{
"action_attempt": {
"status": "pending",
"action_type": "SET_COOL",
"action_attempt_id": "6c5fa5eb-aece-4258-9eeb-24cd24c44a8c",
"result": null,
"error": null
},
"ok": true
}
Request:
const cool_request = await seam.thermostats.cool({
device_id: "518f692b-f865-4590-8c3e-3849e9984c75",
cooling_set_point_celsius: 25
})
​
console.log(cool_request)
Response:
{
actionAttempt: {
status: 'success',
action_attempt_id: '3ef9ff5a-0d50-40a4-9ef4-94f44e923e6e',
action_type: 'SET_COOL',
result: {},
error: null
}
}
Request:
$cool_request = $seam->thermostats->cool(
device_id: "518f692b-f865-4590-8c3e-3849e9984c75",
cooling_set_point_celsius: 25
);
Response:
None
Request:
var deviceId = "518f692b-f865-4590-8c3e-3849e9984c75";
seam.thermostats().update(ThermostatsUpdateRequest.builder()
.deviceId(deviceId)
.defaultClimateSetting(ThermostatsUpdateRequestDefaultClimateSetting.builder()
.hvacModeSetting(HvacModeSetting.COOL)
.coolingSetPointCelsius(25.0)
.manualOverrideAllowed(true)
.build())
.build());
Device thermostat = seam.thermostats()
.get(ThermostatsGetRequest.builder()
.deviceId(deviceId)
.build());
System.out.println("Thermostat ID: " + thermostat.getDeviceId());
System.out.println("Mode: " + thermostat.getProperties().getCurrentClimateSetting().get().getHvacModeSetting());
System.out.println("Cooling set point (Celsius): " +
thermostat.getProperties().getCurrentClimateSetting().get().getCoolingSetPointCelsius());
Response:
Thermostat ID: 518f692b-f865-4590-8c3e-3849e9984c75
Mode: Optional[cool]
Cooling set point (Celsius): Optional[25.0]
Request:
cool_request, uErr := client.Thermostats.Cool(context.Background(), &api.ThermostatsCoolRequest{
DeviceId: "518f692b-f865-4590-8c3e-3849e9984c75",
CoolingSetPointCelsius: api.Float64(25),
})
​
if uErr != nil {
return uErr
}
​
fmt.Println(cool_request)
return nil
Response:
{
"action_attempt": {
"status": "pending",
"action_type": "SET_COOL",
"action_attempt_id": "3ef9ff5a-0d50-40a4-9ef4-94f44e923e6e",
"result": null,
"error": null
},
"ok": true
}

Set a Thermostat to Heat-Cool Mode

You can set a thermostat to operate in heat-cool (also known as "auto") mode and specify desired set point temperatures for both heating and cooling. By establishing the set points, the thermostat activates the associated heating and cooling systems as needed to maintain the specified temperature range.
Set the HVAC mode to heat_cool by providing the device_id of the thermostat and both the heating set point and the cooling set point in Celsius or Fahrenheit.
Python
cURL (bash)
JavaScript
PHP
Java
Go
Request:
heat_and_cool_request = seam.thermostats.heat_cool(
device = "518f692b-f865-4590-8c3e-3849e9984c75",
heating_set_point_celsius = 20,
cooling_set_point_celsius = 25
)
​
pprint(heat_and_cool_request)
Response:
ActionAttempt(action_attempt_id='8050ec59-7f29-4d0d-9842-dedaf304740d',
action_type='SET_HEAT_COOL',
status='success',
result={},
error=None)
Request:
curl -X 'POST' \
'https://connect.getseam.com/thermostats/heat_cool' \
-H 'accept: application/json' \
-H 'Authorization: Bearer ${API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"device_id": "518f692b-f865-4590-8c3e-3849e9984c75",
"heating_set_point_celsius": 20,
"cooling_set_point_celsius": 25
}'
Response:
{
"action_attempt": {
"status": "pending",
"action_type": "SET_HEAT_COOL",
"action_attempt_id": "961b93c0-0397-4737-b96b-1379f6715a2f",
"result": null,
"error": null
},
"ok": true
}
Request:
const heat_cool_request = await seam.thermostats.heatCool({
device_id: "518f692b-f865-4590-8c3e-3849e9984c75",
heating_set_point_celsius: 20,
cooling_set_point_celsius: 25,
})
Response:
{
actionAttempt: {
status: 'success',
action_attempt_id: '13229a60-38ce-4fec-bd93-85674e2257ff',
action_type: 'SET_HEAT_COOL',
result: {},
error: null
}
}
Request:
$heat_cool_request = $seam->thermostats->heat_cool(
device_id: "518f692b-f865-4590-8c3e-3849e9984c75",
heating_set_point_celsius: 20,
cooling_set_point_celsius: 25
);
Response:
None
Request:
var deviceId = "518f692b-f865-4590-8c3e-3849e9984c75";
seam.thermostats().update(ThermostatsUpdateRequest.builder()
.deviceId(deviceId)
.defaultClimateSetting(ThermostatsUpdateRequestDefaultClimateSetting.builder()
.hvacModeSetting(HvacModeSetting.HEAT_COOL)
.heatingSetPointCelsius(20.0)
.coolingSetPointCelsius(25.0)
.manualOverrideAllowed(true)
.build())
.build());
Device thermostat = seam.thermostats()
.get(ThermostatsGetRequest.builder()
.deviceId(deviceId)
.build());
System.out.println("Thermostat ID: " + thermostat.getDeviceId());
System.out.println("Mode: " + thermostat.getProperties().getCurrentClimateSetting().get().getHvacModeSetting());
System.out.println("Heating set point (Celsius): " +
thermostat.getProperties().getCurrentClimateSetting().get().getHeatingSetPointCelsius());
System.out.println("Cooling set point (Celsius): " +
thermostat.getProperties().getCurrentClimateSetting().get().getCoolingSetPointCelsius());
Response:
Thermostat ID: 518f692b-f865-4590-8c3e-3849e9984c75
Mode: Optional[heat_cool]
Heating set point (Celsius): Optional[20.0]
Cooling set point (Celsius): Optional[25.0]
Request:
heat_cool_request, uErr := client.Thermostats.HeatCool(context.Background(), &api.ThermostatsHeatCoolRequest{
DeviceId: "518f692b-f865-4590-8c3e-3849e9984c75",
HeatingSetPointCelsius: api.Float64(20),
CoolingSetPointCelsius: api.Float64(25),
})
​
if uErr != nil {
return uErr
}
​
fmt.Println(heat_cool_request)
return nil
Response:
{
"action_attempt": {
"status": "pending",
"action_type": "SET_HEAT_COOL",
"action_attempt_id": "922a3c60-98bb-4020-b6d9-cf556deacf0f",
"result": null,
"error": null
},
"ok": true
}

Turn off Heating and Cooling

You can set a thermostat to operate in "off" mode, which deactivates the associated heating and cooling systems. In this state, the thermostat does not regulate indoor temperatures.
Set the HVAC mode to off by providing the device_id of the thermostat.
Python
cURL (bash)
JavaScript
PHP
Java
Go
Request:
off_request = seam.thermostats.off(
device = "518f692b-f865-4590-8c3e-3849e9984c75"
)
​
pprint(off_request)
Response:
ActionAttempt(action_attempt_id='ef94c8b2-3ff0-4e56-a97e-033ca07ba0fd',
action_type='SET_THERMOSTAT_OFF',
status='success',
result={},
error=None)
Request:
curl -X 'POST' \
'https://connect.getseam.com/thermostats/off' \
-H 'accept: application/json' \
-H 'Authorization: Bearer ${API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"device_id": "518f692b-f865-4590-8c3e-3849e9984c75"
}'
Response:
{
"action_attempt": {
"status": "pending",
"action_type": "SET_THERMOSTAT_OFF",
"action_attempt_id": "724563fb-d8a4-46b3-81ce-5cbf26008c83",
"result": null,
"error": null
},
"ok": true
}
Request:
const off_request = await seam.thermostats.off({
device_id: "518f692b-f865-4590-8c3e-3849e9984c75"
})
​
console.log(off_request)
Response:
{
actionAttempt: {
status: 'success',
action_attempt_id: 'fffbe81e-f098-4c5f-b4a2-410dd036ae5b',
action_type: 'SET_THERMOSTAT_OFF',
result: {},
error: null
}
}
Request:
$off_request = $seam->thermostats->off(
device_id: "518f692b-f865-4590-8c3e-3849e9984c75"
);
Response:
None
Request:
var deviceId = "518f692b-f865-4590-8c3e-3849e9984c75";
seam.thermostats().update(ThermostatsUpdateRequest.builder()
.deviceId(deviceId)
.defaultClimateSetting(ThermostatsUpdateRequestDefaultClimateSetting.builder()
.hvacModeSetting(HvacModeSetting.OFF)
.build())
.build());
Device thermostat = seam.thermostats()
.get(ThermostatsGetRequest.builder()
.deviceId(deviceId)
.build());
System.out.println("Thermostat ID: " + thermostat.getDeviceId());
System.out.println(