
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 错误代码参考。