此页面由 Cloud Translation API 翻译。

温控器

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

sdm.devices.types.THERMOSTAT

特征

参考

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

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

响应

{}

节能模式

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

请求

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 特征不会返回温度设定值。

更改温度设定值

只能在温控器处于 HEAT、COOL 或 HEATCOOL 模式时更改温度设定值，并且允许的设定值对应于温控器的当前模式。当节能模式关闭或节能模式设为 MANUAL_ECO 时，无法更改温度设定值。

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

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

模式	命令	字段
制热	SetHeat	`heatCelsius`
酷	SetCool	`coolCelsius`
制冷	SetRange	`heatCelsius`，`coolCelsius`

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

如果恒温器处于节能模式，

例如，如需在温控器处于 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" : "18a88716-c522-4d3f-ba2c-21bb6ed60566",
  "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" : "e5c090dc-8cdd-4e03-b912-a2be833a98e3",
  "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/}如果开启 HVAC 系统时没有出现延迟，系统会同时发送所有这三个事件。

错误

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

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

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