온도 조절기 기기 가이드

온도 조절기 기기 유형은 여러 Home API 트레잇을 사용하여 구현할 수 있지만 기본 트레잇은 Thermostat입니다. 다음은 온도 조절기 기기의 필수 및 선택적 트레잇입니다.

Home API 기기 유형 특성 샘플 앱 사용 사례

온도 조절기

ThermostatDevice

온도, 습도 또는 점유 상태에 관한 센서가 내장 또는 별도로 제공되며 원하는 온도를 설정할 수 있는 기기입니다. 온도 조절기는 난방/냉방 장치 (예: 실내 공기 처리기)에 난방 또는 냉방 요구사항 알림을 전송하거나 난방 또는 냉방 장치를 직접 제어하는 메커니즘을 포함할 수 있습니다.

필수 트레잇
     matter Identify
     matter Thermostat

선택적 트레잇
     matter Thermostat User Interface Configuration
     google Extended Thermostat
온도 조절기

자동화 API 지원

다음 Thermostat 트레잇과 요소가 Automation API에서 지원됩니다.

형질 트레잇 유형 요소 유형 요소
온도 조절기 matter 명령어 SetpointRaiseLower
온도 조절기 matter 속성 activePresetHandle
온도 조절기 matter 속성 localTemperature
온도 조절기 matter 속성 숙박 인원
온도 조절기 matter 속성 occupiedCoolingSetpoint
온도 조절기 matter 속성 occupiedHeatingSetpoint
온도 조절기 matter 속성 outdoorTemperature
온도 조절기 matter 속성 setpointChangeSource
온도 조절기 matter 속성 systemMode
온도 조절기 matter 속성 temperatureSetpointHold
온도 조절기 matter 속성 temperatureSetpointHoldDuration
온도 조절기 matter 속성 thermostatRunningMode
온도 조절기 matter 속성 thermostatRunningState
온도 조절기 matter 속성 unoccupiedCoolingSetpoint
온도 조절기 matter 속성 unoccupiedHeatingSetpoint
ExtendedThermostat google 속성 activePresetHandle
ExtendedThermostat google 속성 activeRemoteTemperatureSensorIds
ExtendedThermostat google 속성 averageLocalTemperature
ExtendedThermostat google 속성 extendedRunningMode
ExtendedThermostat google 속성 extendedSystemMode
SimplifiedThermostat google 명령어 SetSystemMode
SimplifiedThermostat google 속성 systemMode

주변 온도 가져오기

Thermostat을 사용하여 주변 온도 가져오기

Thermostat 트레잇을 사용하여 온도 조절기의 주변 온도를 가져오려면 localTemperature 속성을 읽습니다.

Device API

// Get the ambient temperature
val thermostat = home.devices().list().first { device -> device.has(Thermostat) }

val thermostatTraitFlow: Flow<Thermostat?> =
  thermostat
    .type(ThermostatDevice)
    .mapNotNull { it.standardTraits.thermostat }
    .distinctUntilChanged()

val localTempFlow = thermostatTraitFlow.mapNotNull { it?.localTemperature }

Automation API

val automation = automation {
  sequential {
    val starterNode = starter<_>(thermostat, ThermostatDevice, Thermostat)

    // If the temperature is higher than 35C...
    condition { expression = starterNode.localTemperature greaterThan 35 }

    // ...and the automation hasn't been run for at least an hour...
    suppressFor(Duration.ofHours(1))

    // ...broadcast a message
    action(speaker, SpeakerDevice) {
      command(AssistantBroadcast.broadcast("It's very hot outside."))
    }
  }
}

TemperatureMeasurement를 사용하여 주변 온도 가져오기

TemperatureMeasurement 트레잇을 사용하여 온도 조절기의 주변 온도를 가져오려면 measuredValue 속성을 읽습니다.

Device API

val temperatureTraitFlow: Flow<TemperatureMeasurement?> =
  thermostat
    .type(TemperatureSensorDevice)
    .map { it.standardTraits.temperatureMeasurement }
    .distinctUntilChanged()

val localTemp: Short? = temperatureTraitFlow.first()?.measuredValue

Automation API

val automation = automation {
  sequential {
    val temperature = starter<_>(thermostat, ThermostatDevice, TemperatureMeasurement)
    val stateReaderNode = stateReader<_>(light, DimmableLightDevice, OnOff)
    condition() {
      val expr1 = temperature.measuredValue greaterThanOrEquals 35
      val expr2 = stateReaderNode.onOff equals true
      expression = expr1 and expr2
    }
    action(light, DimmableLightDevice) { command(OnOff.on()) }
  }
}

ExtendedThermostat을 사용하여 평균 온도 가져오기

여러 센서의 평균 온도를 가져오려면 ExtendedThermostat 트레잇의 averageLocalTemperature 속성을 읽습니다.

Device API

// Get the average temperature
val thermostat = home.devices().list().first { device -> device.has(TemperatureSensorDevice) }

val temperatureTraitFlow: Flow<TemperatureMeasurement?> =
  thermostat
    .type(TemperatureSensorDevice)
    .map { it.standardTraits.temperatureMeasurement }
    .distinctUntilChanged()

val localTemp: Short? = temperatureTraitFlow.first()?.measuredValue

Automation API

val automation = automation {
  sequential {
    val temperature = starter<_>(thermostat, ThermostatDevice, ExtendedThermostat)
    val stateReaderNode = stateReader<_>(light, DimmableLightDevice, OnOff)
    //  if the average temperature is >= 35C
    condition() {
      val expr1 = temperature.averageLocalTemperature greaterThanOrEquals 35
      val expr2 = stateReaderNode.onOff equals true
      expression = expr1 and expr2
    }
    // Turn on the light
    action(light, DimmableLightDevice) { command(OnOff.on()) }
  }
}

주변 습도 가져오기

RelativeHumidityMeasurement 트레잇을 사용하여 온도 조절기의 주변 습도를 가져오려면 measuredValue 속성을 읽습니다.

Device API

// Get the ambient humidity

val humidityTraitFlow: Flow<RelativeHumidityMeasurement?> =
  humiditySensingThermostat
    .type(HumiditySensorDevice)
    .map { it.standardTraits.relativeHumidityMeasurement }
    .distinctUntilChanged()

val localHumidity: UShort? = humidityTraitFlow.first()?.measuredValue

Automation API

val automation = automation {
  sequential {
    val humidity = starter<_>(thermostat, HumiditySensorDevice, RelativeHumidityMeasurement)
    val stateReaderNode = stateReader<_>(light, DimmableLightDevice, OnOff)
    // if the ambient humidity is >= 80%
    condition() {
      val expr1 = (humidity.measuredValue greaterThanOrEquals 80u)
      val expr2 = (stateReaderNode.onOff equals true)
      expression = expr1 and expr2
    }
    // Turn on the light
    action(light, DimmableLightDevice) { command(OnOff.on()) }
  }
}

표시되는 온도 눈금 선택

온도 조절기 디스플레이에 사용되는 온도 측정 단위를 변경하려면 ThermostatUserInterfaceConfigurationTraittemperatureDisplayMode 속성을 TemperatureDisplayModeEnum.Celsius 또는 TemperatureDisplayModeEnum.Fahrenheit로 설정합니다.

Device API

// Set the displayed temperature scale to Fahrenheit
val uiConfig =
  home
    .devices()
    .list()
    .filter { device -> device.has(ThermostatUserInterfaceConfiguration) }
    .first()

val uiConfigTraitFlow: Flow<ThermostatUserInterfaceConfiguration?> =
  uiConfig
    .type(ThermostatDevice)
    .map { it.standardTraits.thermostatUserInterfaceConfiguration }
    .distinctUntilChanged()

val uiConfigTrait: ThermostatUserInterfaceConfiguration = uiConfigTraitFlow.first()!!

if (
  uiConfigTrait.supports(ThermostatUserInterfaceConfiguration.Attribute.temperatureDisplayMode)
) {
  val unused =
    uiConfigTrait.update { setTemperatureDisplayMode(TemperatureDisplayModeEnum.Fahrenheit) }
}

Automation API

val automation = automation {
  isActive = true
  sequential {
    val stateReaderNode =
      stateReader<_>(thermostat, ThermostatDevice, ThermostatUserInterfaceConfiguration)

    // When someone says "Show the temperature in Fahrenheit",
    val unused =
      starter<_>(structure, VoiceStarter.OkGoogleEvent) {
        parameter(VoiceStarter.OkGoogleEvent.query("Show the temperature in Fahrenheit"))
      }
    // if the temperature isn't being shown in Fahrenheit
    condition() {
      expression =
        stateReaderNode.temperatureDisplayMode notEquals TemperatureDisplayModeEnum.Fahrenheit
    }
    // display the current temperature using Fahrenheit
    action(thermostat, ThermostatDevice) {
      update(ThermostatUserInterfaceConfiguration) {
        setTemperatureDisplayMode(TemperatureDisplayModeEnum.Fahrenheit)
      }
    }
  }
}

작동 모드 변경

값이 ThermostatTrait.Attributes.SystemModeEnum로 정의된 ThermostatTrait.Attributes.systemMode 속성을 설정하여 온도 조절기를 ThermostatTrait.SystemModeEnum로 정의된 특정 작동 모드로 제한할 수 있습니다.

Device API

val thermostatDevice = structure.devices().list().first { device -> device.has(Thermostat) }

val thermostatTraitFlow: Flow<Thermostat?> =
  thermostat.type(ThermostatDevice).map { it.standardTraits.thermostat }.distinctUntilChanged()

val thermostatTrait: Thermostat = thermostatTraitFlow.first()!!

// Set the system mode to Auto
if (thermostatTrait.supports(Thermostat.Attribute.systemMode)) {
  val unused = thermostatTrait.update { setSystemMode(SystemModeEnum.Auto) }
}

Automation API

val automation = automation {
  isActive = true
  // When the door lock state changes
  sequential {
    val doorLockEvent = starter<_>(doorLock, DoorLockDevice, LockOperationEvent)
    val stateReaderNode = stateReader<_>(thermostat, ThermostatDevice, SimplifiedThermostat)

    // if the door is unlocked and the thermostat is in Eco mode
    condition() {
      val expr1 = (doorLockEvent.lockOperationType equals LockOperationTypeEnum.Unlock)
      val expr2 = (stateReaderNode.systemMode equals SimplifiedThermostatSystemModeEnum.Eco)
      expression = expr1 and expr2
    }

    // Set the thermostat to Auto mode
    action(thermostat, ThermostatDevice) {
      command(SimplifiedThermostat.setSystemMode(SimplifiedThermostatSystemModeEnum.Auto))
    }
  }
}

온도 조절기가 SystemModeEnum.Auto로 설정된 경우 ThermostatRunningModeEnum의 값으로 채워진 ThermostatTrait.Attributes.thermostatRunningMode에서 온도 조절기의 작동 모드에 관한 추가 정보를 읽을 수 있습니다.

Device API

// Get the current thermostat running mode

val runningModeTraitFlow: Flow<Thermostat?> =
  thermostat.type(ThermostatDevice).map { it.standardTraits.thermostat }.distinctUntilChanged()

val runningMode: ThermostatTrait.ThermostatRunningModeEnum? =
  runningModeTraitFlow.first()?.thermostatRunningMode

Automation API

val automation = automation {
  isActive = true
  sequential {
    val stateReaderNode = stateReader<_>(thermostat, ThermostatDevice, Thermostat)
    // at 10:00am
    val unused =
      starter<_>(structure, Time.ScheduledTimeEvent) {
        parameter(Time.ScheduledTimeEvent.clockTime(LocalTime.of(10, 0, 0, 0)))
      }

    // if the thermostat is in Auto mode and is currently cooling
    condition() {
      val expr1 = (stateReaderNode.systemMode equals ThermostatTrait.SystemModeEnum.Auto)
      val expr2 =
        (stateReaderNode.thermostatRunningMode equals
          ThermostatTrait.ThermostatRunningModeEnum.Cool)
      expression = expr1 and expr2
    }
    // announce that it's in Cool mode
    action(structure) {
      command(AssistantBroadcast.broadcast("The thermostat is currently running in Cool mode."))
    }
  }
}

SimplifiedThermostatTrait는 자동화에서 작동 모드를 설정하는 프로세스를 간소화하도록 설계되었습니다. SimplifiedThermostatTrait를 사용하여 온도 조절기의 작동 모드를 변경하려면 값이 SimplifiedThermostatTrait.SystemModeEnum로 정의된 SetSystemModeCommand를 사용합니다.

이 트레잇은 Automation API에서만 사용할 수 있습니다.

Automation API

val automation = automation {
  isActive = true

  sequential {
    // When the presence state changes...
    val starterNode = starter<_>(structure, AreaPresenceState)
    // ...and if the area is unoccupied...
    condition() {
      expression = starterNode.presenceState equals PresenceState.PresenceStateVacant
    }
    // Set the thermostat to Eco mode
    action(thermostat, ThermostatDevice) {
      command(SimplifiedThermostat.setSystemMode(SimplifiedThermostatSystemModeEnum.Eco))
    }
  }
}

온도 조절기가 작동할 수 있는 시스템 모드를 확인하려면 ThermostatTrait.Attributes.controlSequenceOfOperation를 읽습니다. 이 값은 ThermostatTrait.ControlSequenceOfOperationEnum에 의해 결정됩니다.

Device API

// Get the controlSequenceOfOperation
val standardTraitFlow: Flow<Thermostat?> =
  thermostat.type(ThermostatDevice).map { it.standardTraits.thermostat }.distinctUntilChanged()

val controlSequenceOfOperation: ThermostatTrait.ControlSequenceOfOperationEnum? =
  standardTraitFlow.first()?.controlSequenceOfOperation

Automation API

val automation = automation {
  isActive = true
  sequential {
    val stateReaderNode = stateReader<_>(thermostat, ThermostatDevice, Thermostat)
    // When someone says "Switch to cool mode",
    val unused =
      starter<_>(structure, VoiceStarter.OkGoogleEvent) {
        parameter(VoiceStarter.OkGoogleEvent.query("Switch to cool mode"))
      }
    // if the thermostat is capable of operating in Cool mode,
    condition() {
      val expr1 =
        stateReaderNode.controlSequenceOfOperation notEquals
          ControlSequenceOfOperationEnum.HeatingOnly
      val expr2 =
        stateReaderNode.controlSequenceOfOperation notEquals
          ControlSequenceOfOperationEnum.HeatingWithReheat
      expression = expr1 and expr2
    }

    action(thermostat, ThermostatDevice) {
      // switch to Cool mode
      update(SimplifiedThermostat) {
        command(SimplifiedThermostat.setSystemMode(SimplifiedThermostatSystemModeEnum.Cool))
      }
    }
  }
}

프로그래밍 작업 모드 변경

온도 조절기의 프로그래밍 작업 모드는 ThermostatthermostatProgrammingOperationMode를 사용하여 변경할 수 있으며, 이 값은 ProgrammingOperationModeBitmap에 의해 정의됩니다.

Device API

val thermostatTraitFlow: Flow<Thermostat?> =
  thermostat.type(ThermostatDevice).map { it.standardTraits.thermostat }.distinctUntilChanged()

val thermostatTrait: Thermostat = thermostatTraitFlow.first()!!

if (thermostatTrait.supports(Thermostat.Attribute.thermostatProgrammingOperationMode)) {
  val programmingOperationMode = thermostatTrait.thermostatProgrammingOperationMode!!

  // Enable autoRecovery on the thermostatProgrammingOperationMode
  val unused =
    thermostatTrait.update {
      setThermostatProgrammingOperationMode(
        ThermostatTrait.ProgrammingOperationModeBitmap(
          programmingOperationMode.scheduleActive,
          true,
          programmingOperationMode.economy,
        )
      )
    }
}

Automation API

// When someone says "Reset programming operation mode"
val automation = automation {
  isActive = true
  sequential {
    val unused =
      starter<_>(structure, VoiceStarter.OkGoogleEvent) {
        parameter(VoiceStarter.OkGoogleEvent.query("Reset programming operation mode"))
      }
    // Set all the flags on the programming operation mode
    action(thermostat, ThermostatDevice) {
      update(Thermostat) {
        setThermostatProgrammingOperationMode(ProgrammingOperationModeBitmap(true, true, true))
      }
    }
  }
}

온도 설정값 변경

Thermostat를 사용하여 온도 설정치를 변경하려면 ThermostatTrait.SetpointRaiseLowerCommand를 호출합니다.

Device API

val thermostatTraitFlow: Flow<Thermostat?> =
  thermostat.type(ThermostatDevice).map { it.standardTraits.thermostat }.distinctUntilChanged()

val thermostatTrait: Thermostat = thermostatTraitFlow.first()!!

// lower the temperature setpoint by 1 degree C
thermostatTrait.setpointRaiseLower(amount = 1, mode = SetpointRaiseLowerModeEnum.Cool)

Automation API

val automation = automation {
  isActive = true
  sequential {
    val stateReaderNode = stateReader<_>(thermostat, ThermostatDevice, Thermostat)
    // At 10:00pm
    val unused =
      starter<_>(structure, Time.ScheduledTimeEvent) {
        parameter(Time.ScheduledTimeEvent.clockTime(LocalTime.of(22, 0, 0, 0)))
      }
    // if the setpoint is warmer than 19C
    condition() { expression = stateReaderNode.occupiedCoolingSetpoint greaterThan 19 }

    // lower the temperature setpoint by 5 degrees
    action(thermostat, ThermostatDevice) {
      command(Thermostat.setpointRaiseLower(SetpointRaiseLowerModeEnum.Cool, 5))
    }
  }
}

온도 설정값 우선순위 지정

ThermostatTraittemperatureSetpointHold 속성을 TemperatureSetpointHoldEnum.SetpointHoldOn로 설정하여 온도 설정점이 사전 프로그래밍된 일정보다 우선 적용되도록 하거나 TemperatureSetpointHoldEnum.SetpointHoldOff로 설정하여 일정이 우선 적용되도록 할 수 있습니다.

Device API

val thermostatTraitFlow: Flow<Thermostat?> =
  thermostat.type(ThermostatDevice).map { it.standardTraits.thermostat }.distinctUntilChanged()

val thermostatTrait: Thermostat = thermostatTraitFlow.first()!!

if (thermostatTrait.supports(Thermostat.Attribute.temperatureSetpointHold)) {
  // Set temperatureSetpointHold to SetpointHoldOn
  // allowing temperature setpoints to override any preprogrammed schedules.

  val unused =
    thermostatTrait.update {
      setTemperatureSetpointHold(TemperatureSetpointHoldEnum.SetpointHoldOn)
    }

Automation API

val automation = automation {
  isActive = true
  sequential {

    // When someone says "Prioritize thermostat setpoint"
    val unused =
      starter<_>(structure, VoiceStarter.OkGoogleEvent) {
        parameter(VoiceStarter.OkGoogleEvent.query("Prioritize thermostat setpoint"))
      }
    // make temperature setpoints override any preprogrammed schedules.
    action(thermostat, ThermostatDevice) {
      val unused2 =
        update(Thermostat) {
          setTemperatureSetpointHold(TemperatureSetpointHoldEnum.SetpointHoldOn)
        }
    }
  }

ThermostatTrait.Attributes.temperatureSetpointHoldDuration를 설정하여 설정점 유지가 활성화되는 시간을 제어합니다.

Device API

val thermostatTraitFlow: Flow<Thermostat?> =
  thermostat.type(ThermostatDevice).map { it.standardTraits.thermostat }.distinctUntilChanged()

val thermostatTrait: Thermostat = thermostatTraitFlow.first()!!

if (thermostatTrait.supports(Thermostat.Attribute.temperatureSetpointHoldDuration)) {
  // Set the setpoint hold duration to 60 minutes
  val unused = thermostatTrait.update { setTemperatureSetpointHoldDuration(60u) }
}

Automation API

val automation = automation {
  isActive = true
  sequential {
    val stateReaderNode = stateReader<_>(thermostat, ThermostatDevice, Thermostat)
    val unused = starter<_>(thermostat, ThermostatDevice, Thermostat)

    // if the temperature setpoint hold duration is less than 60 minutes...
    condition() { expression = stateReaderNode.temperatureSetpointHoldDuration.lessThan(60u) }

    // ...and the automation hasn't been run for at least 24 hours...
    suppressFor(Duration.ofHours(24))

    // ...set the temperature setpoint hold duration to 60 minutes
    action(thermostat, ThermostatDevice) {
      val unused2 = update(Thermostat) { setTemperatureSetpointHoldDuration(60u) }
    }
  }
}

온도 조절기 Hold 상태가 종료되는 방식과 시점을 결정하는 온도 설정값 유지 정책을 변경하려면 ThermostatTrait.SetTemperatureSetpointHoldPolicyCommand를 호출합니다.

유효한 값은 TemperatureSetpointHoldPolicyBitmap에 따라 결정됩니다.

Device API

val thermostatTraitFlow: Flow<Thermostat?> =
  thermostat.type(ThermostatDevice).map { it.standardTraits.thermostat }.distinctUntilChanged()

val thermostatTrait: Thermostat = thermostatTraitFlow.first()!!
if (thermostatTrait.supports(Thermostat.Attribute.temperatureSetpointHoldPolicy)) {

  // Set the temperature setpoint hold policy to holdDurationElapsedOrPresetChanged
  val unused =
    thermostatTrait.setTemperatureSetpointHoldPolicy(
      ThermostatTrait.TemperatureSetpointHoldPolicyBitmap(
        holdDurationElapsed = false,
        holdDurationElapsedOrPresetChanged = true,
      )
    )
}

val automation = automation {
  isActive = true
  sequential {

    // When someone says "Set my preferred hold duration",
    val unused =
      starter<_>(structure, VoiceStarter.OkGoogleEvent) {
        parameter(VoiceStarter.OkGoogleEvent.query("Set my preferred hold duration"))
      }

    // set the temperature setpoint hold policy to holdDurationElapsedOrPresetChanged
    action(thermostat, ThermostatDevice) {
      command(
        Thermostat.setTemperatureSetpointHoldPolicy(
          TemperatureSetpointHoldPolicyBitmap(
            holdDurationElapsed = false,
            holdDurationElapsedOrPresetChanged = true,
          )
        )
      )
    }
  }
}