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:
The corresponding set points in Fahrenheit or Celsius
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: Confirm Capabilities
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.
Before you attempt to set the current HVAC or fan mode settings for a thermostat, be sure to confirm that your thermostat has the capability to perform these operations. You can inspect the capabilities of a thermostat by checking the following capability flags for the device:
device.can_hvac_heat
device.can_hvac_cool
device.can_hvac_heat_cool
device.can_turn_off_hvac
Use Get Device for a specific device to return these capability flags. Then, use an if statement or similar check to confirm that the relevant flag is both present and true before attempting to set the corresponding HVAC mode or fan setting.
If any of these capability flags is false or not present, you can view the properties of the device, errors or warnings for the device, and events related to the device to learn more about the cause of these issues. For example, you could examine device.properties.online. In addition, you could look for a device.disconnected event.
Device(
device_id='11111111-1111-1111-1111-444444444444',
can_hvac_heat=True, // You can use seam.thermostats.heat() on this device.
can_hvac_cool=True, // You can use seam.thermostats.cool() on this device.
can_hvac_heat_cool=True, // You can use seam.thermostats.heat_cool() on this device.
can_turn_off_hvac=True, // You can use seam.thermostats.off() on this device.
...
)
Request:
# Use GET or POST.curl-X'GET' \'https://connect.getseam.com/devices/get' \-H'accept: application/json' \-H"Authorization: Bearer ${SEAM_API_KEY}" \-H'Content-Type: application/json' \-d'{ "device_id": "11111111-1111-1111-1111-444444444444"}'
Response:
{"lock": {"device_id":"11111111-1111-1111-1111-444444444444","can_hvac_heat":true,// You can use /thermostats/heat on this device."can_hvac_cool":true,// You can use /thermostats/cool on this device."can_hvac_heat_cool":true,// You can use /thermostats/heat_cool on this device."can_turn_off_hvac":true,// You can use /thermostats/off on this device. ... },"ok":true}
{ device_id: '11111111-1111-1111-1111-444444444444', can_hvac_heat:true,// You can use seam.thermostats.heat() on this device. can_hvac_cool:true,// You can use seam.thermostats.cool() on this device. can_hvac_heat_cool:true,// You can use seam.thermostats.heatCool() on this device. can_turn_off_hvac:true,// You can use seam.thermostats.off() on this device. ...}
<
Seam::Device:0x00438
device_id="11111111-1111-1111-1111-444444444444"
can_hvac_heat=true, // You can use client.thermostats.heat() on this device.
can_hvac_cool=true, // You can use client.thermostats.cool() on this device.
can_hvac_heat_cool=true, // You can use client.thermostats.heat_cool() on this device.
can_turn_off_hvac=true, // You can use client.thermostats.off() on this device.
...
>
{"device_id":"11111111-1111-1111-1111-444444444444","can_hvac_heat":true,// You can use $seam->thermostats->heat() on this device."can_hvac_cool":true,// You can use $seam->thermostats->cool() on this device."can_hvac_heat_cool":true,// You can use $seam->thermostats->heat_cool() on this device."can_turn_off_hvac":true,// You can use $seam->thermostats->off() on this device. ...}
{
"device_id": "11111111-1111-1111-1111-444444444444",
"can_hvac_heat": true, // You can use seam.Thermostats.Heat() on this device.
"can_hvac_cool": true, // You can use seam.Thermostats.Cool() on this device.
"can_hvac_heat_cool": true, // You can use seam.Thermostats.HeatCool() on this device.
"can_turn_off_hvac": true, // You can use seam.Thermostats.Off() on this device.
...
}
{"device_id":"11111111-1111-1111-1111-444444444444","can_hvac_heat":true,// You can use seam.thermostats.heat() on this device."can_hvac_cool":true,// You can use seam.thermostats.cool() on this device."can_hvac_heat_cool":true,// You can use seam.thermostats.heatCool() on this device."can_turn_off_hvac":true,// You can use seam.thermostats.off() on this device. ...}
{"device_id":"11111111-1111-1111-1111-444444444444","can_hvac_heat":true,// You can use client.Thermostats.Heat() on this device."can_hvac_cool":true,// You can use client.Thermostats.Cool() on this device."can_hvac_heat_cool":true,// You can use client.Thermostats.HeatCool() on this device."can_turn_off_hvac":true,// You can use client.Thermostats.Off() on this device. ...}
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:
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:
Request:
# Get the thermostat.thermostat = seam.devices.get( device_id="518f692b-f865-4590-8c3e-3849e9984c75")# Confirm that the thermostat supports heat mode.if thermostat.can_hvac_heat:# Perform the heat request. seam.thermostats.heat( device_id ="518f692b-f865-4590-8c3e-3849e9984c75", heating_set_point_celsius =20 )
# Get the thermostat.constthermostat=awaitseam.devices.get({ device_id:"518f692b-f865-4590-8c3e-3849e9984c75"});// Confirm that the thermostat supports heat mode.if (thermostat.can_hvac_heat) {// Perform the heat request.awaitseam.thermostats.heat({ device_id:thermostat.device_id, heating_set_point_celsius:20 })};
// Get the thermostat.$thermostat = $seam->devices->get( device_id:"5ce2cd35-09b1-458c-bb08-51ee83c35be7");// Confirm that the thermostat supports heat mode.if ($thermostat->can_hvac_heat) {// Perform the heat request. $seam->thermostats->heat( device_id: $thermostat->device_id, heating_set_point_celsius:20);}
Response:
None
Request:
// Get the thermostat.Device thermostat =seam.devices().get(DevicesGetRequest.builder().deviceId("518f692b-f865-4590-8c3e-3849e9984c75").build());// Confirm that the thermostat supports heat mode.if (thermostat.getCanHvacHeat()){// Perform the heat request.seam.thermostats().heat(ThermostatsHeatRequest.builder().deviceId(thermostat.getDeviceId()).heatingSetPointCelsius(20.0).build());}
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.
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.
Request:
# Get the thermostat.thermostat = seam.devices.get( device_id="518f692b-f865-4590-8c3e-3849e9984c75")# Confirm that the thermostat supports heat mode.if thermostat.can_hvac_heat:# Perform the heat request. seam.thermostats.heat( device_id ="518f692b-f865-4590-8c3e-3849e9984c75", heating_set_point_celsius =20 )
# Get the thermostat.constthermostat=awaitseam.devices.get({ device_id:"518f692b-f865-4590-8c3e-3849e9984c75"});// Confirm that the thermostat supports heat mode.if (thermostat.can_hvac_heat) {// Perform the heat request.awaitseam.thermostats.heat({ device_id:thermostat.device_id, heating_set_point_celsius:20 })};
// Get the thermostat.$thermostat = $seam->devices->get( device_id:"5ce2cd35-09b1-458c-bb08-51ee83c35be7");// Confirm that the thermostat supports heat mode.if ($thermostat->can_hvac_heat) {// Perform the heat request. $seam->thermostats->heat( device_id: $thermostat->device_id, heating_set_point_celsius:20);}
Response:
None
Request:
// Get the thermostat.Device thermostat =seam.devices().get(DevicesGetRequest.builder().deviceId("518f692b-f865-4590-8c3e-3849e9984c75").build());// Confirm that the thermostat supports heat mode.if (thermostat.getCanHvacHeat()){// Perform the heat request.seam.thermostats().heat(ThermostatsHeatRequest.builder().deviceId(thermostat.getDeviceId()).heatingSetPointCelsius(20.0).build());}
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.
Request:
# Get the thermostat.
thermostat = seam.devices.get(
device_id="518f692b-f865-4590-8c3e-3849e9984c75"
)
# Confirm that the thermostat supports cool mode.
if thermostat.can_hvac_cool:
# Perform the cool request.
seam.thermostats.cool(
device_id = "518f692b-f865-4590-8c3e-3849e9984c75",
cooling_set_point_celsius = 25
)
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.
Request:
# Get the thermostat.
thermostat = seam.devices.get(
device_id="518f692b-f865-4590-8c3e-3849e9984c75"
)
# Confirm that the thermostat supports heat-cool mode.
if thermostat.can_hvac_heat_cool:
# Perform the heat_cool request.
seam.thermostats.heat_cool(
device_id = "518f692b-f865-4590-8c3e-3849e9984c75",
heating_set_point_celsius = 20,
cooling_set_point_celsius = 25
)
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.
Request:
# Get the thermostat.
thermostat = seam.devices.get(
device_id="518f692b-f865-4590-8c3e-3849e9984c75"
)
# Confirm that the thermostat supports off mode.
if thermostat.can_turn_off_hvac:
# Perform the off request.
seam.thermostats.off(
device_id = "518f692b-f865-4590-8c3e-3849e9984c75"
)
# Get the thermostat.
const thermostat = await seam.devices.get({
device_id: "518f692b-f865-4590-8c3e-3849e9984c75"
});
// Confirm that the thermostat supports off mode.
if (thermostat.can_turn_off_hvac) {
// Perform the off request.
await seam.thermostats.off({
device_id: thermostat.device_id
})
};
// Get the thermostat.
$thermostat = $seam->devices->get(
device_id: "5ce2cd35-09b1-458c-bb08-51ee83c35be7"
);
// Confirm that the thermostat supports off mode.
if ($thermostat->can_turn_off_hvac) {
// Perform the off request.
$seam->thermostats->off(
device_id: $thermostat->device_id
);
}
Response:
None
Request:
// Get the thermostat.
Device thermostat = seam.devices()
.get(DevicesGetRequest.builder()
.deviceId("518f692b-f865-4590-8c3e-3849e9984c75")
.build());
// Confirm that the thermostat supports off mode.
if (thermostat.getCanTurnOffHvac())
{
// Perform the off request.
seam.thermostats().off(ThermostatsOffRequest.builder()
.deviceId(thermostat.getDeviceId())
.build());
}
You can configure the fan associated with a thermostat to operate in either on or auto mode. In the on setting, the fan runs continuously, while in the auto setting, the fan operates based on temperature needs and system demands.
Set the fan mode by providing the device_id of the thermostat and specifying the desired fan mode setting.