
Smart Device Management (SDM) API 支援所有 Google Nest 溫度控制器型號。這些裝置會傳回「THERMOSTAT」裝置類型:
sdm.devices.types.THERMOSTAT
特徵
參考資料
以下特徵、指令或事件與這個群組相關:
特徵 | 說明 | 指令 |
---|---|---|
連線能力 | 這個特徵屬於任何具有連線資訊的裝置。 | |
Fan | 這個特徵屬於任何具有系統控制風扇功能的裝置。 | SetTimer |
濕度 | 此特徵屬於任何具有用於測量濕度感應器的裝置。 | |
資訊 | 這個特徵屬於任何裝置,可用於提供裝置相關資訊。 | |
設定 | 這個特徵屬於任何裝置,可提供裝置相關設定資訊。 | |
溫度 | 這個特徵屬於任何具有溫度感應器的裝置。 | |
ThermostatEco | 這個特徵屬於支援 ECO 模式的溫度控制器裝置類型。 | SetMode |
ThermostatHvac | 這個特徵屬於可回報 HVAC 詳細資料的溫度控制器裝置類型。 | |
ThermostatMode | 這個特徵屬於支援不同溫度控制器模式的 THERMOSTAT 裝置類型。 | 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 Thermostat 可顯示攝氏或華氏溫度,但 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"
}
}
回應
{}
節能模式
如要開啟節能模式,請使用 ThermostatEco 特徵的 SetMode 指令,將 MANUAL_ECO 設為模式:
要求
POST /enterprises/project-id/devices/device-id:executeCommand
{
"command" : "sdm.devices.commands.ThermostatEco.SetMode
",
"params" : {
"mode" : "MANUAL_ECO"
}
}
回應
{}
這項指令會根據 Eco 模式的目前狀態或變更,影響其他特徵:
- 如果節能模式為「關閉」,溫度控制器模式會預設為上次啟用的標準模式 (HEAT、COOL、HEATCOOL 或 OFF)。
- 如果節能模式為 MANUAL_ECO:
- 系統會拒絕 ThermostatTemperatureSetpoint 特徵的指令。
- ThermostatTemperatureSetpoint 特徵不會傳回溫度設定點。
變更溫度設定點
溫度設定點只能在溫度控制器處於暖氣、冷氣或暖冷氣模式時變更,且允許的設定點必須與溫度控制器目前的模式相符。在模式為「關閉」或節能模式設為「MANUAL_ECO」時,無法變更溫度設定點。
溫度控制器必須處於與呼叫指令相對應的模式,才能變更溫度設定點。變更設定點的指令和欄位會因溫度控制器模式而異。
舉例來說,如要發出 SetHeat 指令,溫度控制器必須先處於 HEAT 模式:
模式 | 指令 | 欄位 |
---|---|---|
加熱 | SetHeat | heatCelsius |
冷氣 | SetCool | coolCelsius |
HEATCOOL | SetRange | heatCelsius 、coolCelsius |
請注意,設定點指令只會使用攝氏為參數,但 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 特徵傳回的 heatCelsius
和 coolCelsius
設定點是由使用者設定,無法透過 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 錯誤,請使用Connectivity 特徵,檢查裝置的連線狀態是否為離線。檢查裝置是否已連上網際網路,並確認 Nest 服務是否已啟用。
如果您已啟用事件,應該也會收到資源事件,指出裝置已離線:
酬載
{
"eventId" : "6a7e4a81-2978-499e-bbfb-c216438ea078",
"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" : "3ec67ac6-3977-4938-af47-5ba38e3e86e5",
"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 狀態變更事件可能不會與溫度控制器模式變更事件同時傳送。
舉例來說,為了保護空調系統,溫度控制器啟動暖氣或冷氣模式時,有時會延遲。在這種情況下,變更溫度控制器模式可能只會在初始時傳送 ThermostatMode 和 ThermostatTemperatureSetpoint 特徵變更的事件,而 ThermostatHvac 特徵變更會在系統實際開啟時傳送為個別事件。如果啟動 HVAC 系統時沒有延遲,系統會同時傳送所有三個事件。
錯誤
系統可能會傳回與此裝置相關的以下錯誤代碼:
錯誤訊息 | 單次點擊收益 | 疑難排解 |
---|---|---|
冷值必須大於熱值。 | INVALID_ARGUMENT |
請確認 heatCelsius 欄位小於指令中的 coolCelsius 欄位。 |
在目前的溫度控制器模式下,不允許執行指令。 | FAILED_PRECONDITION |
根據 ThermostatMode 特徵,部分溫度控制器型號在溫度控制器模式為「關閉」時,不支援變更節能模式。必須先將溫度控制器模式變更為 HEAT、COOL 或 HEATCOOL,才能變更節能模式。 |
溫度控制器風扇無法使用。 | FAILED_PRECONDITION |
溫度控制器沒有風扇功能。無法為此裝置使用風扇相關特徵和指令。 |
溫度自動調節器處於 MANUAL_ECO 模式時,無法執行這項指令。 | FAILED_PRECONDITION |
溫度控制器處於手動節能模式時,無法設定溫度設定點。 |
如需 API 錯誤代碼的完整清單,請參閱 API 錯誤代碼參考資料。