此页面由 Cloud Translation API 翻译。

恒温器

Smart Device Management (SDM) API 支持所有 Google Nest Thermostat 型号。以下设备会返回 THERMOSTAT 设备类型：

sdm.devices.types.THERMOSTAT

trait

参考

以下特征、命令或事件与此群组相关：

特征	说明	命令
连接	此 trait 适用于具有连接信息的任何设备。
风扇	此特征属于具有系统控制风扇的任何设备。	SetTimer
湿度	此 trait 适用于任何具有测量湿度的传感器的设备。
信息	此 trait 属于任何设备，用于提供与设备相关的信息。
设置	此特征属于任何设备，可提供与设备相关的设置信息。
温度	此 trait 适用于任何具有温度测量传感器的设备。
ThermostatEco	此 trait 属于支持 ECO 模式的温控器设备类型。	SetMode
ThermostatHvac	此 trait 属于可报告 HVAC 详细信息的温控器设备类型。
ThermostatMode	此特征属于支持不同温控器模式的 THERMOSTAT 设备类型。	SetMode
ThermostatTemperatureSetpoint	此 trait 属于支持设置目标温度和温度范围的温控器设备类型。	SetHeat SetCool SetRange

JSON

如果 GET 响应中缺少某个特征，表示相应特征或功能目前不适用于设备。如需了解详情，请参阅设备类型。

{
  "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 trait。环境温度是在设备上测量的。

如需读取温控器的环境湿度，请使用Humidity trait。环境湿度是在设备上测量的。

温标

Google Nest Thermostat 能以摄氏度或华氏度为单位来显示温度，但 SDM API 无法设置此刻度。如需确定用户当前设置的温度范围，请使用设置特征。

更改模式

温控器的模式由两个不同的 trait 管理：ThermostatMode 和ThermostatEco。

标准模式

如需将温控器模式更改为 HEAT、COOL 或 HEATCOOL，请使用 ThermostatMode trait 的 SetMode 命令。

此命令还可用于将温控器的模式切换为“关闭”，但不能用于开启节能模式。

例如，如需更改某个标准温控器模式，请执行以下操作：

请求

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

响应

{}

节能模式

如需开启节能模式，请使用 ThermostatEco trait 的 SetMode 命令将模式设为 MANUAL_ECO：

请求

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

响应

{}

此命令会根据经济模式的当前状态或变化影响其他 trait：

如果节能模式处于关闭状态，温控器模式将默认设为上次处于活动状态的标准模式（HEAT、COOL、HEATCOOL 或 OFF）。
如果节能模式为 MANUAL_ECO：

系统会拒绝针对 ThermostatTemperatureSetpoint trait 的命令。
ThermostatTemperatureSetpoint 特征不会返回温度设定值。

更改温度设定值

只有在温控器处于“供暖”“制冷”或“适温”模式时，才能更改温度设定值，并且允许的设定值与温控器的当前模式相对应。当模式关闭或节能模式设置为 MANUAL_ECO 时，无法更改温度设定值。

在更改温度设定点之前，温控器必须处于与要调用的命令对应的模式。用于更改设定值的命令和字段因温控器模式而异。

例如，如需发出 SetHeat 命令，温控器必须先处于 HEAT 模式：

模式	命令	字段
供暖	SetHeat	`heatCelsius`
COOL	SetCool	`coolCelsius`
HEATCOOL	SetRange	`heatCelsius`，`coolCelsius`

请注意，设定点命令仅接受摄氏度作为参数，但 Google Nest Thermostat 可以显示摄氏度或华氏度的温度。

例如，如需在温控器处于 HEAT 模式时更改温度设定点，请使用 ThermostatTemperatureSetpoint trait 的 SetHeat 命令：

请求

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

响应

{}

节能模式设定点

ThermostatEco trait 返回的 heatCelsius 和 coolCelsius 设定点由用户设置，无法通过 SDM API 更改。

开启或关闭风扇

如果温控器支持风扇，请使用风扇特征的 SetTimer 命令来开启或关闭风扇。打开或关闭温控器时，您可以指定风扇运行时长（以秒为单位）。

例如，要让风扇运行 1 小时，请使用以下代码：

请求

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

响应

{}

如果省略 duration 字段，风扇将默认运行 15 分钟。

检查设备连接

如果设备未响应命令或发送事件，或者您从与设备相关的 API 收到错误，请使用Connectivity trait 检查设备的连接是否处于离线状态。检查设备的互联网连接，并确保 Nest 服务已启动。

如果您已启用事件，则还应收到指示设备已离线的资源事件：

载荷

{
  "eventId" : "366dcbfb-2b0d-4c8c-9ad9-2ff7434f1dc7",
  "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"
  ]
}

对设备事件做出响应

对 trait 字段所做的任何更改都会生成事件。例如，如果温控器的 HVAC 状态更改为 HEATING，您将收到以下 resourceUpdate 事件：

载荷

{
  "eventId" : "1e9d0340-7543-4a6f-b498-7c12a77f0b27",
  "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"
  ]
}

系统会针对与此设备类型关联的所有 trait 触发事件。如果您需要在集成过程中以某种方式对事件做出响应，请启用事件。

事件的时间

请注意，HVAC 状态变化事件可能不会与温控器模式变化事件同时传送。

例如，为了保护 HVAC 系统，有时会延迟启动温控器的供暖或制冷模式。在这种情况下，更改温控器模式可能最初只会发送 ThermostatMode 和 ThermostatTemperatureSetpoint trait 更改事件，并在系统实际开启后，稍后再发送 ThermostatHvac trait 更改事件作为单独的事件。如果 HVAC 系统的开启没有延迟，系统会同时发送所有三种事件。

错误

系统可能会返回与此设备相关的以下错误代码：

错误消息	RPC	问题排查
制冷值必须大于热值。	`INVALID_ARGUMENT`	确保命令中的 `heatCelsius` 字段小于 `coolCelsius` 字段。
不允许在当前温控器模式下执行该命令。	`FAILED_PRECONDITION`	根据 ThermostatMode trait，某些温控器型号不支持在温控器模式为“关闭”时更改节能模式。必须先将温控器模式更改为制热、制冷或制热，然后才能更改节能模式。
温控器风扇不可用。	`FAILED_PRECONDITION`	温控器不具备风扇功能。无法对此设备使用与风扇相关的特征和命令。
当温控器处于 MANUAL_ECO 模式时，不允许执行此命令。	`FAILED_PRECONDITION`	当温控器处于手动节能模式时，无法设置温度设定点。

如需查看 API 错误代码的完整列表，请参阅 API 错误代码参考。