恒温器

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

sdm.devices.types.THERMOSTAT

特征

参考

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

特征说明命令
网络连接此特征属于具有连接信息的所有设备。
粉丝此特征属于系统能够控制风扇的任何设备。SetTimer
湿度此特征属于任何具有用于测量湿度的传感器的设备。
信息此特征属于设备相关信息的任何设备。
设置对于设备相关设置信息,此特征属于任何设备。
温度此特征适用于任何配有传感器来测量温度的设备。
ThermostatEco此特征属于支持 ECO 模式的 THERMOSTAT 设备类型。SetMode
ThermostatHvac此特征属于可报告 HVAC 详细信息的 THERMOSTAT 设备类型。
ThermostatMode此特征属于支持不同温控器模式的温控器设备类型。SetMode
ThermostatTemperatureSetpoint此特征属于支持设置目标温度和温度范围的温控器设备类型。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 无法设置刻度。如需确定用户当前设置的温标,请使用设置 特征。

更改模式

温控器的模式由两个不同的特征进行管理: ThermostatModeThermostatEco

标准模式

如需将温控器模式更改为 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:

更改温度设定值

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

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

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

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

请注意,setpoint 命令仅接受摄氏度作为参数,但 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 特征返回的 heatCelsiuscoolCelsius 设置点由用户设置,无法通过 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" : "b7705246-9224-46af-b5f2-b2af8437cd0e",
  "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 状态更改为“正在供暖”,您将收到以下 resourceUpdate 事件:

载荷

{
  "eventId" : "849df9a2-9a28-452e-9b34-5490fc93d88b",
  "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 系统,有时会延迟启动温控器的供暖或制冷模式。在这种情况下,更改温控器模式可能最初只会发送 ThermostatModeThermostatTemperatureSetpoint 特征变化的事件,其中 ThermostatHvac 实际上是作为单独的事件开启的。 如果开启 HVAC 系统没有延迟,则所有三个事件都会同时发送。

错误数

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

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

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