本頁面由 Cloud Translation API 翻譯而成。

溫度控制器

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

sdm.devices.types.THERMOSTAT

性狀

參考資料

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

性狀	說明	指令
連線能力	這項特性適用於所有有連線資訊的裝置。
粉絲	這項特性是指任何具備系統風扇的裝置，	SetTimer
溼度	這個特性適用於所有含有感應器以測量濕度的裝置。
資訊	這項特性與任何裝置相關資訊有關。
設定	這項特性屬於任何裝置相關設定資訊，
溫度	裝置本身擁有感應器，可用來測量溫度。
ThermostatEco	這個特性屬於支援 ECO 模式的 THERMOSTAT 裝置類型。	SetMode
ThermostatHvac	該特性屬於可回報 HVAC 詳細資料的 THERMOSTAT 裝置類型。
ThermostatMode	這個特性屬於支援不同溫度控制器模式的 THERMOSTAT 裝置類型。	SetMode
TheThemostatTemperatureSetpoint	這個特性屬於可設定目標溫度和溫度範圍的 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 設定。如要判斷使用者目前設定的溫度比例，請使用Settings trat。

變更模式

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

回應

{}

這個指令會根據其他生態系統的目前狀態或變更，影響其他特質：

如果關閉節能模式，溫度控制器模式會預設為最活躍的標準模式 (HEAT、COOL、HeatCOOL 或 OFF)。
若生態模式為 MANUAL_ECO：

ThermostatTemperatureSetpoint 的指令會遭到拒絕。
溫度設定點不會由熱能溫度設定傳回。

調整溫度設定點

只有在溫度控制器為暖氣、COOL 或 HEATCOOL 模式，且允許的設定點對應至溫度控制器的目前模式時，才能變更溫度設定點。模式關閉或溫度模式設為 MANUAL_ECO 時，無法變更溫度設定點。

溫度控制器必須位於與變更溫度設定點之前呼叫的指令相對應的模式。用於變更設定點的指令和欄位會因溫度控制器模式而有所不同。

舉例來說，如要發出 SetHeat 指令，溫度控制器必須先使用 HEAT 模式：

模式	指令	欄位
加熱	SetHeat	`heatCelsius`
哥倫比亞	SetCool	`coolCelsius`
匈牙利	SetRange	`heatCelsius`、`coolCelsius`

請注意，setpoint 指令只能以攝氏為單位度數來測量溫度，但 Google Nest Thermostat 可顯示溫度以攝氏或華氏為單位。

如果溫度控制器處於節能模式，

舉例來說，如要在溫度控制器處於暖氣模式時變更溫度設定點，請使用 ThermostatTemperatureSetpoint 特徵的 SetHeat 指令：

要求

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.ThermostatTemperatureSetpoint.SetHeat",
  "params" : {
    "heatCelsius" : 22.0
  }
}

回應

{}

節能模式設定點

TherestatEco 特徵會回傳的 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 收到錯誤訊息，請使用連線檢查裝置的連線是否為 OFFLINE 狀態。檢查裝置與網際網路的連線，並確認 Nest Service 已啟用。

如果您已啟用事件，請一併收到資源事件，指出裝置已離線：

酬載

{
  "eventId" : "dd05ec21-82db-46f0-8878-4fedcf1af200",
  "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" : "d9d86df5-407f-4917-8286-fe07d5c3dd3b",
  "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 如果開啟 HVAC 系統時沒有延遲，系統會同時傳送三個事件。

錯誤

系統可能會針對這部裝置傳回下列錯誤代碼：

錯誤訊息	RPC	疑難排解
冷值必須大於熱值。	`INVALID_ARGUMENT`	確認 `heatCelsius` 欄位小於指令中的 `coolCelsius` 欄位。
當前溫度控制器模式不允許使用指令。	`FAILED_PRECONDITION`	根據溫度控制器的溫度控制器模式，在溫度控制器關閉時，不支援某些節能模式。你必須先將溫度控制器模式變更為 HEAT、COOL 或 HEATCOOL，才能變更節能模式。
無法使用風扇模式，	`FAILED_PRECONDITION`	溫度控制器沒有風扇功能這部裝置無法使用粉絲相關特性和指令。
不得在 MANUAL_ECO 模式下使用溫度控制器。	`FAILED_PRECONDITION`	如果溫度控制器處於手動節能模式，就無法設定溫度設定點。

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