恒温器

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

sdm.devices.types.THERMOSTAT

特征

参考

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

特征说明命令
连接此特征属于具有连接信息的任何设备。
风扇此特征属于任何具有控制风扇的系统能力的设备。SetTimer
湿度此特征属于任何具有湿度测量传感器的设备。
信息此特征属于任何设备，用于提供设备相关信息。
设置此特征属于任何设备，用于提供与设备相关的设置信息。
温度此特征属于任何具有温度测量传感器的设备。
ThermostatEco此特征属于支持节能模式的温控器设备类型。SetMode
ThermostatHvac此特征属于可以报告 HVAC 详细信息的温控器设备类型。
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
    }
  }
}

温度和湿度

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

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

温标

Google Nest 温控器可以显示摄氏度或华氏度温度，但无法通过 SDM API 设置温标。如需确定用户当前设置的温标，请使用Settings 特征。

更改模式

温控器的模式由两个不同的特征管理：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：

更改温度设定值

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

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

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

模式 命令 字段
HEAT SetHeat heatCelsius
COOL SetCool coolCelsius
HEATCOOL SetRange heatCelsius、coolCelsius

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

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

请求

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

响应

{}

节能模式设定值

ThermostatEco 特征返回的 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 特征检查设备的连接状态是否为 OFFLINE。检查设备与互联网的连接，并确保 Nest 服务正常运行。

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

载荷

{
  "eventId" : "c10c1ae5-2bf3-434b-a77f-42a2b94f689b",
  "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" : "880ace18-f08a-4703-8d46-ddba8a7c9542",
  "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"
  ]
}

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

活动时间

请注意，暖通空调状态更改事件的传送时间可能与温控器模式更改事件的传送时间不同。

例如，有时为了保护暖通空调系统，恒温器在启动供暖或制冷模式时会延迟。在这种情况下，更改温控器模式可能只会先发送 ThermostatMode 和 ThermostatTemperatureSetpoint 特征更改事件，而 ThermostatHvac 特征更改事件会在系统实际开启后作为单独的事件发送。如果开启 HVAC 系统时没有延迟，这三个事件将同时发送。

错误

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

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

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