Setting the Current HVAC and Fan Mode Settings

Learn how to configure the current climate settings on a thermostat.

You can use the following Seam API "imperative" endpoints to set the current HVAC and fan mode settings for a connected thermostat, individually:

• /thermostats/heat

• /thermostats/cool

• /thermostats/heat_cool

• /thermostats/off

• /thermostats/set_fan_mode

You can also use the /thermostats/set_hvac_mode endpoint to set a thermostat to the desired HVAC mode, including heat, cool, heat_cool, eco (for Google Nest), or off, depending on the capabilities of the device. For heat, cool, and heat_cool, also specify the desired heating and cooling set points, as appropriate.

Note that it's important to check the capabilities of a thermostat before attempting to use an imperative endpoint. For example, if a thermostat is attached to an HVAC system that does not have cooling capabilities, you cannot use /thermostats/cool or /thermostats/heat_cool. To check the capabilities of a thermostat, retrieve the thermostat and confirm the relevant capability flags.

These imperative operations return an action attempt that enables you to track the progress of the action. Poll this action attempt, until the action completes.

Further, Seam emits a thermostat.temperature_reached_set_point event when the thermostat reports a temperature within 1° Celsius of the heating or cooling temperature that you requested.

---

HVAC Settings

When you use an imperative endpoint to set the HVAC settings for a thermostat, you specify the HVAC mode and the desired set points in Fahrenheit or Celsius.

To set the HVAC mode and set points, issue a thermostat heat, cool, heat_cool, eco (for Google Nest), or off request and include the desired set points in the body of the request.

---

Fan Mode Settings

Seam supports the following fan mode settings:

Fan mode	Description
on	The fan runs all the time, regardless of whether the HVAC system is cooling or heating.
auto	The fan runs whenever the HVAC system is cooling or heating but does not run at other times.
circulate	The fan runs for a specific number of minutes each hour, regardless of whether the HVAC system is cooling or heating. To find out whether a thermostat supports this setting, view its device.properties.available_fan_mode_settings property.

---

Process Overview

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

1. Confirm the capabilities of the thermostat.

   See Before You Begin: Confirm Capabilities.

2. Execute the imperative climate setting request. See the following instructions:

   • Set a Thermostat to Heat Mode

   • Set a Thermostat to Cool Mode

   • Set a Thermostat to Heat-Cool Mode

   • Turn off Heating and Cooling

   • Set the Fan Mode Setting

3. Poll the action attempt. See Poll the Action Attempt.

4. If desired, configure a webhook to watch for a thermostat.temperature_reached_set_point event that indicates that the thermostat has reported a temperature within 1° Celsius of the heating or cooling set point that you requested. See Webhooks.

---

Before You Begin: Confirm Capabilities

Before you attempt to set the HVAC or fan mode settings for a thermostat, be sure to confirm that your device has the capability to perform these operations. You can inspect the capabilities of a device 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 the /devices/get endpoint 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 perform the imperative thermostat action.

If the relevant capability flag 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.

Python

Request:

seam.devices.get(
  device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
)

Response:

Device(
  device_id='a4b775e3-feb2-4c6b-8e78-a73ec2d70b61',
  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.
  ...
)

cURL (bash)

JavaScript

Ruby

PHP

C#

---

Set a Thermostat to Heat Mode

You can set a thermostat to heat mode or use the /thermostats/set_hvac_mode endpoint, 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.

Issue the thermostat heat request, providing the device_id of the thermostat and the heating_set_point_celsius or heating_set_point_fahrenheit.

Python

Request:

# Get the thermostat.
thermostat = seam.devices.get(
  device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
)

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

ActionAttempt(
  action_attempt_id='97125745-15d9-4970-b5be-c34ec3ce1c81',
  action_type='SET_HVAC_MODE',
  status='success',
  result={},
  error=None
)

cURL (bash)

JavaScript

Ruby

PHP

C#

---

Set a Thermostat to Cool Mode

You can set a thermostat to cool mode or use the /thermostats/set_hvac_mode endpoint, 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.

Issue the thermostat cool request, providing the device_id of the thermostat and the cooling_set_point_celsius or cooling_set_point_fahrenheit.

Python

Request:

# Get the thermostat.
thermostat = seam.devices.get(
  device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
)

# Confirm that the thermostat supports cool mode.
if thermostat.can_hvac_cool:
  # Perform the cool request.
  seam.thermostats.cool(
    device_id = thermostat.device_id,
    cooling_set_point_celsius = 25
  )

Response:

ActionAttempt(
  action_attempt_id='87478724-0e30-4fed-9f2a-456971b7b04f',
  action_type='SET_HVAC_MODE',
  status='success',
  result={},
  error=None
)

cURL (bash)

JavaScript

Ruby

PHP

C#

---

Set a Thermostat to Heat-Cool Mode

You can set a thermostat to heat-cool (also known as "auto") mode or use the /thermostats/set_hvac_mode endpoint, 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.

Issue the thermostat heat_cool request, providing the device_id of the thermostat and the following set points:

• heating_set_point_celsius or heating_set_point_fahrenheit

• cooling_set_point_celsius or cooling_set_point_fahrenheit

Python

Request:

# Get the thermostat.
thermostat = seam.devices.get(
  device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
)

# 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 = thermostat.device_id,
    heating_set_point_celsius = 20,
    cooling_set_point_celsius = 25
  )

Response:

ActionAttempt(
  action_attempt_id='8050ec59-7f29-4d0d-9842-dedaf304740d',
  action_type='SET_HVAC_MODE',
  status='success',
  result={},
  error=None
)

cURL (bash)

JavaScript

Ruby

PHP

C#

---

Turn off Heating and Cooling

You can set a thermostat to "off" mode or use the /thermostats/set_hvac_mode endpoint, which deactivates the associated heating and cooling systems. In this state, the thermostat does not regulate indoor temperatures.

Issue the thermostat off request, providing the device_id of the thermostat.

Python

Request:

# Get the thermostat.
thermostat = seam.devices.get(
  device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61"
)

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

ActionAttempt(
  action_attempt_id='ef94c8b2-3ff0-4e56-a97e-033ca07ba0fd',
  action_type='SET_HVAC_MODE',
  status='success',
  result={},
  error=None
)

cURL (bash)

JavaScript

Ruby

PHP

C#

---

Set the Fan Mode Setting

You can configure the fan mode setting for a thermostat. For details about the supported fan modes, see Fan Mode Settings.

Set the fan mode setting by providing the device_id of the thermostat and specifying the desired fan_mode_setting.

Python

Request:

seam.thermostats.set_fan_mode(
  device_id = "a4b775e3-feb2-4c6b-8e78-a73ec2d70b61",
  fan_mode_setting = "auto"
)

Response:

ActionAttempt(
  action_attempt_id='9c9b584b-c645-4ce0-a9c2-79b6f1db2396',
  action_type='SET_FAN_MODE',
  status='success',
  result={},
  error=None
)

cURL (bash)

JavaScript

Ruby

PHP

C#

---

Poll the Action Attempt

The imperative HVAC or fan mode setting request returns an action attempt. Use the action_attempt_id from this response to poll the associated action attempt using the /action_attempts/get request. When the setting modification completes successfully, the status of the action attempt changes to success.

Python

Request:

seam.action_attempts.get(
  action_attempt_id = "9c9b584b-c645-4ce0-a9c2-79b6f1db2396"
)

Response:

ActionAttempt(
  action_attempt_id='9c9b584b-c645-4ce0-a9c2-79b6f1db2396',
  action_type='SET_FAN_MODE',
  status='success',
  result={},
  error=None
)

cURL (bash)

JavaScript

Ruby

PHP

C#