恒温器

所有 Google Nest Thermostat 模型 Smart Device Management (SDM) API 集成。这些设备返回温控器 设备类型:

sdm.devices.types.THERMOSTAT

特征

参考

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

特征说明命令
畅连乐享此特征属于具有连接信息的任何设备。
粉丝此特征属于具有系统控制风扇的任何设备。SetTimer
湿度此特征属于具有湿度测量传感器的任何设备。
信息此特征属于任何用于获取设备相关信息的设备。
设置此特征属于任何设备,可提供与设备相关的设置信息。
温度此特征属于具有温度测量传感器的任何设备。
ThermostatEco此特征属于支持 ECO 模式的 THERMOSTAT 设备类型。SetMode
ThermostatHvac此特征属于可以报告 HVAC 详情的 THERMOSTAT 设备类型。
ThermostatMode此特征属于支持不同温控器模式的 THERMOSTAT 设备类型。SetMode
ThermostatTemperatureSetpoint此特征属于支持设置目标温度和温度范围的 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 and 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 作为模式, 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:

更改温度设定值

仅当温控器处于开启状态时,才能更改温度设定值 HEAT、COOL 或 HEATCOOL 模式;以及 允许的设定值与温控器的当前模式相对应。体温 模式关闭或 节能模式已设为 MANUAL_ECO。

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

例如,要发出 SetHeat 命令,温控器必须先处于 HEAT 模式:

模式 命令 字段
供暖 SetHeat heatCelsius
SetCool coolCelsius
制热 SetRange heatCelsiuscoolCelsius

请注意,虽然设置点命令的 Google Nest Thermostat 能以摄氏度或华氏度为单位来显示温度。

例如,更改温控器开启时的温度设定值 制热模式,请使用 ThermostatTemperatureSetpoint 特征的 SetHeat 命令:

请求

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

响应

{}

节能模式设定值

返回的 heatCelsiuscoolCelsius 设定点 ThermostatEco 特征由用户设置, 无法通过 SDM API 进行更改。

打开或关闭风扇

如果温控器支持风扇,请使用风扇特征的 SetTimer 命令来开启或关闭风扇。 打开此设置时,您可以指定风扇运行时长,即 。

例如,要让风扇运行一小时,请使用以下代码:

请求

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

响应

{}

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

检查设备连接

如果设备没有响应命令或发送事件,或者您收到 与设备相关的 API 错误,请使用 网络连接 特征,检查 设备的网络连接,以处于“离线”状态。请检查设备的 连接到互联网,并确保 Nest 服务正常运行。

如果您启用了事件,则应该也收到了资源事件 这表明设备已离线:

载荷

{
  "eventId" : "0425a61d-a026-4608-8d8d-d76351d444a4",
  "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"
  ]
}

响应设备事件

对特征字段的任何更改都会生成一个事件。 例如,您会收到 以下 resourceUpdate 事件(如果温控器的 HVAC) 状态已更改为“HEATING”:

载荷

{
  "eventId" : "24b17b95-a286-4471-901f-5bdd4a05be28",
  "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 and ThermostatTemperatureSetpoint 特征发生变化, ThermostatHvac 特征更改之后会单独发送 事件。如果 HVAC 系统开启时没有延迟, 系统会同时发送三个事件

错误

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

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

请参阅 API 错误代码参考 API 错误代码的完整列表。