此页面由 Cloud Translation API 翻译。

温控器

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

sdm.devices.types.THERMOSTAT

特征

参考

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

特征	说明	命令
网络连接	此特征属于具有连接信息的所有设备。
粉丝	此特征属于任何具有系统控制风扇的设备。	Set 计时器
湿度	此特征属于任何具有传感器以测量湿度的设备。
信息	此特征属于任何与设备相关的信息的设备。
设置	此特征属于与设备相关的设置信息的任何设备。
温度	此特征属于任何具有传感器测量温度的设备。
温控器	此特征属于支持 ECO 模式的 ThermOSTAT 设备类型。	SetMode
温控器	此特征属于可报告 HVAC 详细信息的 ThermOSTAT 设备类型。
温控器模式	此特征属于支持不同温控器模式的 ThermOSTAT 设备类型。	SetMode
温控器温度设置	此特征属于支持设置目标温度和温度范围的 ThermOSTAT 设备类型。	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
    }
  }
}

温度和湿度

如需读取温控器的环境温度，请使用温度特征。设备测量的是环境温度。

如需读取温控器的环境湿度，请使用湿度特征。环境湿度在设备进行测量。

温标

Google Nest Thermostat 能够以摄氏度或华氏度显示温度，但 SDM API 无法设置体重秤。如需确定用户当前设置的温度标度，请使用设置特征。

更改模式

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

标准模式

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

此命令还可用于关闭温控器的模式。它无法用于开启节能模式。

例如，如需更改某个标准温控器模式，请使用以下代码：

请求

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

响应

{}

节能模式

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

请求

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

响应

{}

该命令会根据节能模式的当前状态或发生的更改影响其他特征：

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

ThermostatTemperatureSetpoint 特征的命令将被拒绝。
ThermostatTemperatureSetpoint 特征不会返回温度设定值。

更改温度设定值

仅当温控器处于恒温、制冷或健康温度模式时，温度设定值才能更改，并且允许的设定值与温控器的当前模式相对应。当模式处于关闭状态或节能模式设置为 MANUAL_ECO 时，温度设置值无法更改。

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

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

模式	命令	字段
制热	SetHeat	`heatCelsius`
制冷	SetCool	`coolCelsius`
制热	设置范围	`heatCelsius`、`coolCelsius`

请注意，虽然 Google Nest Thermostat 能够以摄氏度或华氏度显示温度，但只接受以摄氏度为单位的参数。

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

请求

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

响应

{}

节能模式设定值

由 ThermostatEco 特征返回的 heatCelsius 和 coolCelsius setpoint 由用户设置，不能通过 SDM API 更改。

打开或关闭风扇

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

例如，如需让风扇运行一小时，请执行以下操作：

请求

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

响应

{}

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

检查设备连接

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

启用事件后，您还应该收到表示设备已离线的资源事件：

载荷

{
  "eventId" : "cbd1850c-7705-458e-82ea-c6fdf593c8e0",
  "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"
  ]
}

对设备事件做出响应

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

载荷

{
  "eventId" : "be8f70c9-5cd2-45a5-bf7f-fdcc293bd0ca",
  "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"
  ]
}

与此设备类型关联的所有特征都会触发事件。如果您需要在集成过程中以某种方式回应事件，请启用事件。

事件的时间

请注意，HVAC 状态更改事件可能会与温控器模式更改事件同时传递。

例如，为了保护 HVAC 系统，有时启动温控器的供暖或制冷模式会延迟。在此场景中，更改温控器模式可能最初只能发送 ThermostatMode 和 ThermostatTemperatureSetpoint 特征更改， ThermostatHvac}{/19/}{/19/}{/19/}{/19/}{/19/}{/19/}{/19/}{/19/} 如果开启 HVAC 系统时没有延迟，系统会同时发送所有这三个事件。

错误数

相对于此设备，可能会返回以下错误代码：

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

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