溫度控制器

所有 Google Nest Thermostat AI 開發原則 和 Smart Device Management (SDM) API 整合這些裝置會傳回 THERMOSTAT 裝置類型:

sdm.devices.types.THERMOSTAT

特徵

參考資料

下列特徵、指令或事件與此群組相關:

特徵說明指令
連線能力這項特徵適用於所有有連線資訊的裝置。
粉絲凡是能控制風扇的裝置都能使用此特徵。SetTimer
濕度凡是搭載感應器且可測量濕度的裝置,都屬於這項特徵。
資訊此特徵屬於任何裝置相關資訊。
設定這項特徵屬於任何裝置相關設定資訊。
溫度凡是搭載感應器的裝置,都能使用這項特徵。
ThermostatEco這項特徵屬於支援 ECO 模式的 THERMOSTAT 裝置類型。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
    }
  }
}

溫度與濕度

如要讀取溫度控制器的環境溫度,請使用 溫度 特徵。環境 這是裝置測得的溫度。

如果想讀取溫度控制器的環境濕度,請使用 濕度 特徵:環境 裝置濕度是由裝置測得。

溫標

Google Nest Thermostat 可以以攝氏度或攝氏為單位顯示溫度 華氏,但無法透過 SDM API 設定縮放比例。為了判斷 則請使用使用者目前設定的溫度量表 設定 特徵。

變更模式

溫度控制器的模式是由兩種不同特徵所管理: ThermostatMode and ThermostatEco

標準模式

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

回應

{}

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

調整溫度設定點

只有在溫度控制器處於啟用狀態時,才能變更溫度設定點 暖氣、冷氣或暖氣模式 允許的設定點會對應至溫度控制器目前的模式溫度 模式關閉或 節能模式已設為「MANUAL_ECO」。

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

舉例來說,如要發出 SetHeat 指令,溫度控制器必須先進入暖氣模式:

模式 指令 欄位
加熱 SetHeat heatCelsius
酷航 SetCool coolCelsius
熱源 SetRange heatCelsiuscoolCelsius

請注意,設定點指令僅使用攝氏度數做為參數 Google Nest Thermostat 能夠以攝氏或華氏度為單位顯示溫度。

例如在溫度控制器開啟時變更溫度設定點 暖氣模式,請使用 ThermostatTemperatureSetpoint 特徵的 SetHeat 指令:

要求

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

回應

{}

節能模式設定點

heatCelsiuscoolCelsius 使用者會設定 ThermostatEco 特徵 無法透過 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 服務已啟動。

如果已啟用活動,應該也會收到資源事件 表示裝置已離線:

酬載

{
  "eventId" : "0425a61d-a026-4608-8d8d-d76351d444a4",
  "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"
  ]
}

回應裝置事件

對特徵欄位所做的任何變更都會產生事件。 舉例來說,您可能會收到 以下 resourceUpdate 事件 (如果溫度控制器的空調發生狀況) 狀態已變更為暖氣:

酬載

{
  "eventId" : "24b17b95-a286-4471-901f-5bdd4a05be28",
  "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"
  ]
}

系統會針對與此裝置類型相關聯的所有特徵觸發事件。啟用 事件 整合過程中

事件時間

請注意,空調狀態變更的事件,可能不會與活動同時傳送 溫度控制器模式的變化

舉例來說 a 溫度控制器的暖氣或冷氣模式啟動延遲情形,以保護空調 有些人會將 Cloud Storage 視為檔案系統 但實際上不是在此情境下,變更溫度控制器模式時,一開始只會傳送事件 ThermostatMode and ThermostatTemperatureSetpoint 的特徵改變, ThermostatHvac 特徵變更之後會單獨傳送 事件。如果啟用空調系統沒有延遲 就會同時傳送三個事件。

錯誤

關於這部裝置,系統可能傳回下列錯誤代碼:

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

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