온도 조절기 기기 유형은 여러 Home API 트레잇을 사용하여 구현할 수 있지만 기본 트레잇은 Thermostat
입니다. 다음은 온도 조절기 기기의 필수 및 선택적 트레잇입니다.
Home API 기기 유형 | 특성 | 샘플 앱 | 사용 사례 |
---|---|---|---|
온도 조절기온도, 습도 또는 점유 상태에 관한 센서가 내장 또는 별도로 제공되며 원하는 온도를 설정할 수 있는 기기입니다. 온도 조절기는 난방/냉방 장치 (예: 실내 공기 처리기)에 난방 또는 냉방 요구사항 알림을 전송하거나 난방 또는 냉방 장치를 직접 제어하는 메커니즘을 포함할 수 있습니다. |
필수 트레잇 matter Identify matter 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 | 속성 | activePresetHandle | |
ExtendedThermostat | 속성 | activeRemoteTemperatureSensorIds | |
ExtendedThermostat | 속성 | averageLocalTemperature | |
ExtendedThermostat | 속성 | extendedRunningMode | |
ExtendedThermostat | 속성 | extendedSystemMode | |
SimplifiedThermostat | 명령어 | SetSystemMode | |
SimplifiedThermostat | 속성 | 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()) } } }
표시되는 온도 눈금 선택
온도 조절기 디스플레이에 사용되는 온도 측정 단위를 변경하려면 ThermostatUserInterfaceConfigurationTrait
의 temperatureDisplayMode
속성을 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)) } } } }
프로그래밍 작업 모드 변경
온도 조절기의 프로그래밍 작업 모드는 Thermostat
의 thermostatProgrammingOperationMode
를 사용하여 변경할 수 있으며, 이 값은 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)) } } }
온도 설정값 우선순위 지정
ThermostatTrait
의 temperatureSetpointHold
속성을 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, ) ) ) } } }