![](https://developers.google.cn/nest/device-access/images/device-thermostat.png?authuser=8&hl=cs)
所有 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:
- 针对“ ThermostatTemperatureSetpoint ”特征的命令已被拒绝。
- ThermostatTemperatureSetpoint 特征不会返回温度设定值。
更改温度设定值
仅当温控器处于开启状态时,才能更改温度设定值 HEAT、COOL 或 HEATCOOL 模式;以及 允许的设定值与温控器的当前模式相对应。体温 模式关闭或 节能模式已设为 MANUAL_ECO。
在更改设置之前,温控器必须处于与所调用的命令相对应的模式 温度设定值。用于更改设定点的命令和字段因温控器而异 模式。
例如,要发出 SetHeat 命令,温控器必须先处于 HEAT 模式:
模式 | 命令 | 字段 |
---|---|---|
供暖 | SetHeat | heatCelsius |
酷 | SetCool | coolCelsius |
制热 | SetRange | heatCelsius 、coolCelsius |
请注意,虽然设置点命令的 Google Nest Thermostat 能以摄氏度或华氏度为单位来显示温度。
例如,更改温控器开启时的温度设定值 制热模式,请使用 ThermostatTemperatureSetpoint 特征的 SetHeat 命令:
请求
POST /enterprises/project-id/devices/device-id:executeCommand
{
"command" : "sdm.devices.commands.ThermostatTemperatureSetpoint.SetHeat
",
"params" : {
"heatCelsius" : 22.0
}
}
响应
{}
节能模式设定值
返回的 heatCelsius
和 coolCelsius
设定点
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" : "e9fc64cf-84d9-46ae-b305-e4435a5ed06d",
"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" : "77fe1905-dc6f-457a-abcd-6e5230deab28",
"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 错误代码的完整列表。