온도 조절기

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

sdm.devices.types.THERMOSTAT

특성

참조JSON

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

형질설명명령어
연결이 트레잇은 연결 정보가 있는 모든 기기에 속합니다.
팬이 트레잇은 팬을 제어하는 시스템 기능이 있는 모든 기기에 속합니다.SetTimer
습도이 트레잇은 습도를 측정하는 센서가 있는 모든 기기에 속합니다.
정보이 트레잇은 기기 관련 정보의 모든 기기에 속합니다.
설정이 트레잇은 기기 관련 설정 정보의 모든 기기에 속합니다.
온도이 트레잇은 온도를 측정하는 센서가 있는 모든 기기에 속합니다.
ThermostatEco이 트레잇은 ECO 모드를 지원하는 THERMOSTAT 기기 유형에 속합니다.SetMode
ThermostatHvac이 트레잇은 HVAC 세부정보를 보고할 수 있는 THERMOSTAT 기기 유형에 속합니다.
ThermostatMode이 트레잇은 다양한 온도 조절기 모드를 지원하는 THERMOSTAT 기기 유형에 속합니다.SetMode
ThermostatTemperatureSetpoint이 트레잇은 타겟 온도 및 온도 범위 설정을 지원하는 THERMOSTAT 기기 유형에 속합니다.SetHeat
SetCool
SetRange

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은 섭씨 또는 화씨로 온도를 표시할 수 있지만, 설정점 명령은 섭씨만 매개변수로 사용합니다.

예를 들어 온도 조절기가 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를 통해 변경할 수 없습니다.

팬 켜기 또는 끄기

온도 조절기가 팬을 지원하는 경우 팬 트레잇의 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" : "7bfa9f08-b07a-4839-bf2f-3c64b2b40660",
  "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" : "bb46ea3e-e674-4d45-a5da-1eb163bc2b3e",
  "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 오류 코드 참조를 확인하세요.