溫度控制器

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 特徵。

變更模式

溫度控制器的模式由兩個不同的特徵管理: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"
  }
}

回應

{}

這項指令會根據 Eco 模式的目前狀態或變更,影響其他特徵:

  • 如果節能模式為「關閉」,溫度控制器模式會預設為上次啟用的標準模式 (HEAT、COOL、HEATCOOL 或 OFF)。
  • 如果節能模式為 MANUAL_ECO:

變更溫度設定點

溫度設定點只能在溫度控制器處於暖氣、冷氣或暖冷氣模式時變更,且允許的設定點必須與溫度控制器目前的模式相符。在模式為「關閉」或節能模式設為「MANUAL_ECO」時,無法變更溫度設定點。

溫度控制器必須處於與呼叫指令相對應的模式,才能變更溫度設定點。變更設定點的指令和欄位會因溫度控制器模式而異。

舉例來說,如要發出 SetHeat 指令,溫度控制器必須先處於 HEAT 模式:

模式 指令 欄位
加熱 SetHeat heatCelsius
冷氣 SetCool coolCelsius
HEATCOOL SetRange heatCelsiuscoolCelsius

請注意,設定點指令只會使用攝氏為參數,但 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 錯誤,請使用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 狀態變更事件可能不會與溫度控制器模式變更事件同時傳送。

舉例來說,為了保護空調系統,溫度控制器啟動暖氣或冷氣模式時,有時會延遲。在這種情況下,變更溫度控制器模式可能只會在初始時傳送 ThermostatModeThermostatTemperatureSetpoint 特徵變更的事件,而 ThermostatHvac 特徵變更會在系統實際開啟時傳送為個別事件。如果啟動 HVAC 系統時沒有延遲,系統會同時傳送所有三個事件。

錯誤

系統可能會傳回與此裝置相關的以下錯誤代碼:

錯誤訊息 單次點擊收益 疑難排解
冷值必須大於熱值。 INVALID_ARGUMENT 請確認 heatCelsius 欄位小於指令中的 coolCelsius 欄位。
在目前的溫度控制器模式下,不允許執行指令。 FAILED_PRECONDITION 根據 ThermostatMode 特徵,部分溫度控制器型號在溫度控制器模式為「關閉」時,不支援變更節能模式。必須先將溫度控制器模式變更為 HEAT、COOL 或 HEATCOOL,才能變更節能模式。
溫度控制器風扇無法使用。 FAILED_PRECONDITION 溫度控制器沒有風扇功能。無法為此裝置使用風扇相關特徵和指令。
溫度自動調節器處於 MANUAL_ECO 模式時,無法執行這項指令。 FAILED_PRECONDITION 溫度控制器處於手動節能模式時,無法設定溫度設定點。

如需 API 錯誤代碼的完整清單,請參閱 API 錯誤代碼參考資料