온도 조절기

모든 Google Nest Thermostat 모델은 Smart Device Management(SDM) API에서 지원됩니다. 다음 기기는 THERMOSTAT 기기 유형을 반환합니다.

sdm.devices.types.THERMOSTAT

트레잇

참조

다음 트레잇, 명령어 또는 이벤트가 이 그룹과 관련이 있습니다.

형질설명명령어
연결이 트레잇은 연결 정보가 있는 모든 기기에 속합니다.
팬이 특성은 팬을 제어할 수 있는 시스템 기능이 있는 모든 기기에 속합니다.SetTimer
습도이 트레잇은 습도를 측정하는 센서가 있는 모든 기기에 속합니다.
정보이 트레잇은 기기 관련 정보의 모든 기기에 속합니다.
설정이 트레잇은 기기 관련 설정 정보의 모든 기기에 속합니다.
온도이 트레잇은 온도를 측정하는 센서가 있는 모든 기기에 속합니다.
ThermostatEco이 트레잇은 ECO 모드를 지원하는 THERMOSTAT 기기 유형에 속합니다.SetMode
ThermostatHvac이 트레잇은 HVAC 세부정보를 보고할 수 있는 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로 관리됩니다.

표준 모드

온도 조절기 모드를 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"
  }
}

응답

{}

이 명령어는 절전 모드의 현재 상태 또는 절전 모드의 변경사항에 따라 다른 특성에 영향을 미칩니다.

  • 절전 모드가 꺼져 있는 경우 온도 조절기 모드는 마지막으로 활성화되었던 표준 모드 (난방, 냉방, 난방 또는 꺼짐)로 기본 설정됩니다.
  • 절전 모드가 MANUAL_ECO인 경우:

온도 설정값 변경

온도 설정값은 온도 조절기가 HEAT, COOL 또는 HEATCOOL 모드일 때만 변경할 수 있으며 허용되는 설정값은 온도 조절기의 현재 모드에 해당합니다. 모드가 'OFF'이거나 절전 모드가 'MANUAL_ECO'로 설정된 경우 온도 설정치를 변경할 수 없습니다.

온도 설정값을 변경하기 전에 온도 조절기가 호출되는 명령어에 해당하는 모드여야 합니다. 설정값을 변경하는 명령어와 필드는 온도 조절기 모드에 따라 다릅니다.

예를 들어 SetHeat 명령어를 실행하려면 먼저 온도 조절기가 HEAT 모드여야 합니다.

모드 명령어 필드
난방 SetHeat heatCelsius
시원함 SetCool coolCelsius
HEATCOOL SetRange heatCelsius, coolCelsius

Google Nest Thermostat은 섭씨 또는 화씨로 온도를 표시할 수 있지만, 설정점 명령은 섭씨만 매개변수로 사용합니다.

예를 들어 온도 조절기가 난방 모드일 때 온도 설정값을 변경하려면 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 명령어를 사용하여 팬을 켜거나 끌 수 있습니다. 켜는 경우 팬이 작동할 시간을 초 단위로 지정할 수 있습니다.

예를 들어 팬을 1시간 동안 실행하려면 다음을 실행합니다.

요청

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" : "366dcbfb-2b0d-4c8c-9ad9-2ff7434f1dc7",
  "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" : "1e9d0340-7543-4a6f-b498-7c12a77f0b27",
  "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 상태 변경 이벤트가 온도 조절기 모드 변경 이벤트와 동시에 전송되지 않을 수 있습니다.

예를 들어 HVAC 시스템을 보호하기 위해 온도 조절기의 난방 또는 냉방 모드 시작이 지연되는 경우가 있습니다. 이 시나리오에서는 온도 조절기 모드를 변경하면 처음에 ThermostatMode 및 ThermostatTemperatureSetpoint 의 이벤트만 전송될 수 있고, ThermostatHvac의 개별 이벤트가 한 번 켜지면 나중에 실제로 이벤트가 켜집니다. HVAC 시스템을 켜는 데 지연이 없으면 세 가지 이벤트가 모두 동시에 전송됩니다.

오류

이 기기와 관련하여 다음 오류 코드가 반환될 수 있습니다.

오류 메시지 RPC 문제 해결
냉방 값은 난방 값보다 커야 합니다. INVALID_ARGUMENT 명령어의 heatCelsius 필드가 coolCelsius 필드보다 작은지 확인합니다.
현재 온도 조절기 모드에서 사용할 수 없는 명령어입니다. FAILED_PRECONDITION 일부 온도 조절기 모델은 ThermostatMode 트레잇에 따라 온도 조절기 모드가 꺼져 있을 때 절전 모드를 변경하는 기능을 지원하지 않습니다. 절전 모드를 변경하기 전에 온도 조절기 모드를 HEAT, COOL 또는 HEATCOOL로 변경해야 합니다.
온도 조절기 팬을 사용할 수 없습니다. FAILED_PRECONDITION 온도 조절기에는 팬 기능이 없습니다. 이 기기에는 팬 관련 트레잇과 명령어를 사용할 수 없습니다.
온도 조절기가 MANUAL_ECO 모드일 때는 명령이 허용되지 않습니다. FAILED_PRECONDITION 온도 조절기가 수동 에코 모드에 있으면 온도 설정값을 설정할 수 없습니다.

API 오류 코드의 전체 목록은 API 오류 코드 참조를 확인하세요.