溫度控制器

Smart Device Management (SDM) API 支援所有 Google Nest Thermostat 型號。這些裝置會傳回 THERMOSTAT 裝置類型：

sdm.devices.types.THERMOSTAT

特徵

參考資料

以下特徵、指令或事件與這個群組相關：

特徵說明指令
連線能力凡是具備連線資訊的裝置，都屬於這項特徵。
風扇凡是具備風扇控制系統功能的裝置，都屬於這項特徵。SetTimer
濕度只要裝置有可測量濕度的感應器，就屬於這項特徵。
資訊這個特徵屬於任何裝置，可提供裝置相關資訊。
「設定」這個特徵屬於任何裝置，可提供裝置相關設定資訊。
溫度這項特徵屬於任何具備溫度感應器的裝置。
ThermostatEco這個特徵屬於支援節能模式的恆溫器裝置類型。SetMode
ThermostatHvac這項特徵屬於可回報空調詳細資料的 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
    }
  }
}

溫度和濕度

如要讀取溫度控制器的室溫，請使用Temperature 特徵。裝置會測量環境溫度。

如要讀取溫度控制器的環境濕度，請使用 Humidity 特徵。裝置測量的環境濕度。

溫標

Google Nest Thermostat 可以顯示攝氏或華氏溫度，但無法透過 SDM API 設定溫標。如要判斷使用者目前設定的溫度單位，請使用「設定」 特徵。

變更模式

溫度控制器的模式由兩種不同的特徵管理： ThermostatMode 和 ThermostatEco。

標準模式

如要將溫度控制器模式變更為「暖氣」、「冷氣」或「冷暖」，請使用 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"
  }
}

回應

{}

這項指令會根據省電模式的目前狀態或變更，影響其他特徵：

  • 如果「節能」模式為關閉，溫度控制器模式會預設為上次啟用的標準模式 (「暖氣」、「冷氣」、「冷暖」或「關閉」)。
  • 如果節能模式為 MANUAL_ECO：

變更溫度設定點

只有在溫度控制器處於「暖氣」、「冷氣」或「冷暖」模式時，才能變更溫度設定點，且允許的設定點會對應至溫度控制器的目前模式。如果模式為「關閉」，或節能模式設為「手動節能」，就無法變更溫度設定點。

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

舉例來說，如要發出 SetHeat 指令，溫度控制器必須先處於暖氣模式：

模式 指令 欄位
加熱 SetHeat heatCelsius
COOL SetCool coolCelsius
HEATCOOL SetRange heatCelsius、coolCelsius

請注意，設定點指令只會將攝氏溫度做為參數，但 Google Nest 溫度控制器可以顯示攝氏或華氏溫度。

如果溫度控制器處於節能模式，系統會拒絕所有「All Set*」指令。

舉例來說，如要在溫度控制器處於「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 變更。

開啟或關閉風扇

如果溫度控制器支援風扇，請使用 Fan 特徵的 SetTimer 指令開啟或關閉風扇。開啟風扇時，你可以指定風扇運轉時間長度 (以秒為單位)。

舉例來說，如要讓風扇運轉一小時，請說出：

要求

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" : "e915e9ce-f227-42f4-aa76-2a6e1e40dafd",
  "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"
  ]
}

對裝置事件做出反應

只要特徵欄位有任何變更，就會產生事件。 舉例來說，如果溫度控制器的空調狀態變更為「HEATING」，您會收到下列 resourceUpdate 事件：

酬載

{
  "eventId" : "66464d68-b841-49ad-ae25-b896d54d14a9",
  "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 特徵變更事件。如果開啟空調系統時沒有延遲，這三個事件就會同時傳送。

錯誤

與這部裝置相關的錯誤代碼可能如下：

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

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