온도 조절기

Smart Device Management (SDM) API에서는 모든 Google Nest Thermostat 모델이 지원됩니다. 이러한 기기는 온도 조절기 기기 유형을 반환합니다.

sdm.devices.types.THERMOSTAT

특성

참조

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

특성설명명령어
연결이 특성은 연결 정보가 있는 모든 기기에 속합니다.
Fan이 특성은 팬을 제어하는 시스템 기능이 있는 모든 기기에 속합니다.SetTimer
습도이 특성은 습도를 측정하는 센서가 있는 모든 기기에 속합니다.
정보이 특성은 기기 관련 정보가 있는 모든 기기에 속합니다.
설정이 특성은 기기 관련 설정 정보가 있는 모든 기기에 속합니다.
온도이 특성은 온도를 측정하는 센서가 있는 모든 기기에 속합니다.
ThermostatEco이 특성은 ECO 모드를 지원하는 온도 조절기 기기 유형에 속합니다.SetMode
ThermostatHvac이 특성은 HVAC 세부정보를 보고할 수 있는 온도 조절기 기기 유형에 속합니다.
ThermostatMode이 특성은 다양한 온도 조절기 모드를 지원하는 온도 조절기 기기 유형에 속합니다.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 특성을 사용하세요.

모드 변경

온도 조절기의 모드는ThermostatMode 및ThermostatEco라는 두 가지 서로 다른 특성으로 관리됩니다.

표준 모드

온도 조절기 모드를 HEAT, COOL 또는 HEATCOOL로 변경하려면 ThermostatMode 특성의 SetMode 명령어를 사용하세요.

이 명령어는 온도 조절기의 모드를 OFF로 전환하는 데도 사용할 수 있습니다. 절전 모드를 사용 설정하는 데는 사용할 수 없습니다.

예를 들어 표준 온도 조절기 모드 중 하나를 변경하려면 다음 단계를 따르세요.

요청

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인 경우:

온도 설정값 변경

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

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

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

모드 명령어 필드
난방 SetHeat heatCelsius
냉방 SetCool coolCelsius
HEATCOOL SetRange heatCelsius, coolCelsius

Google Nest 온도 조절기는 온도를 섭씨 또는 화씨로 표시할 수 있지만 설정값 명령은 섭씨 단위만 매개변수로 사용합니다.

예를 들어 온도 조절기가 난방 모드일 때 온도 설정값을 변경하려면 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" : "31a9759c-21a6-47d7-acbc-8e854f1000a7",
  "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" : "20388ec2-1a03-4eba-b2fc-aa30616108be",
  "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 특성에 따라 온도 조절기 모드가 OFF일 때 절전 모드 변경을 지원하지 않습니다. 절전 모드를 변경하기 전에 온도 조절기 모드를 HEAT, COOL 또는 HEATCOOL로 변경해야 합니다.
온도 조절기 팬을 사용할 수 없습니다. FAILED_PRECONDITION 온도 조절기에 팬 기능이 없습니다. 이 기기에는 팬 관련 특성과 명령어를 사용할 수 없습니다.
온도 조절 장치가 MANUAL_ECO 모드에 있을 때는 명령이 허용되지 않습니다. FAILED_PRECONDITION 온도 조절기가 수동 절전 모드에 있으면 온도 설정값을 설정할 수 없습니다.

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