자동화는 홈에서 작업과 기기 설정을 자동화하는 방법입니다. 자동화는 Google Home 생태계에서 Google Home app (GHA)의 루틴으로, Google Home for web의 automation script editor을 통해 사용할 수 있었습니다.
이제 Android용 Home API를 통해 Google Home 생태계의 자동화를 사용할 수 있습니다. GHA 루틴 및 script editor에 사용되는 기본 개념과 동일하지만 다음과 같은 Home API를 통해서만 가능한 향상된 기능과 기능을 사용합니다.
- Home API에 표시된 대로 기기의 모든 Matter 표준 및 smart home 특성에 대한 액세스 권한
- 순차, 병렬, 선택 실행 흐름 지원
자동화는 Kotlin에서 자동화를 빌드하도록 설계된 도메인별 언어인 자동화 DSL을 사용하여 작성됩니다.
기기 및 구조 또는 자동화 API와 함께 앱에서 사용하려는 특성과 유형은 초기화 시 등록해야 합니다. Android에서 홈 초기화를 참고하세요.
사용자가 모든 권한을 취소하는 경우 안내
사용자가 모든 권한을 취소하면 기존의 모든 자동화가 작동하지 않습니다. 또한 사용자가 특정 기기에 대한 액세스 권한을 취소하면 해당 기기와 연결된 트리거, 조건, 작업이 작동하지 않습니다.
앱이 시작될 때마다 권한이 여전히 유효한지 확인하세요. 취소된 경우 애플리케이션에 캐시된 데이터를 포함한 모든 이전 데이터가 삭제되었는지 확인합니다.
구조 액세스 권한이 취소되면 StructureAccessRevokedEvent이 클라우드 백엔드에 전송됩니다. 전체 파트너 클라우드 및 모바일 앱 취소 워크플로는 구조 부여를 참고하세요.
개발자 여정
Automation API는 더 큰 개발 여정의 일부입니다. 사용자가 자동화를 사용하고 싶을 때 사용할 수 있도록 구조 및 기기 API를 통합한 후에 제공됩니다.
- 개발자가 자동화를 계획하고 자동화 DSL을 사용하여 정의합니다.
- 개발자가 Kotlin Android 앱에 자동화 정의를 삽입합니다.
- 앱은 Discovery API 또는 Device API를 사용하여 수집된 특성, 속성, 명령어, 이벤트 등 기기에 관한 정보를 기반으로 사용자에게 자동화를 표시합니다.
- Discovery API를 사용하면 앱이 사용자의 입력이 있든 없든 사용자의 구조에 있는 기기 유형과 특성에 맞게 맞춤설정된 자동화 초안을 생성할 수 있습니다.
- 기기 API는 검색 API와 거의 동일한 정보를 제공할 수 있지만 자동화 사용 사례에 최적화되어 있지는 않습니다. 자세한 내용은 기기 API와 Discovery API 비교를 참고하세요.
- 앱은 선택한 구조에 키가 지정된 실제 자동화를 만듭니다.
- 이제 자동화가 사용자의 구조에서 제공되며 구조 API 메서드를 사용하여 실행하거나 삭제할 수 있습니다.
사용자는 언제든지 자동화의 새 인스턴스를 만들어 다른 구조를 선택하거나 앱 로직에 따라 다른 기기 집합을 선택할 수 있습니다. 이렇게 할 때마다 앱은 자동화의 새 인스턴스를 생성합니다.
가장 기본적인 시나리오에서는 비교적 기본적인 작업을 실행하는 사전 정의된 자동화를 사용자에게 제안할 수 있습니다. 또는 사용자가 자신의 필요에 맞게 맞춤설정할 수 있는 자동화의 스켈레톤을 표시할 수도 있습니다. 또는 사용자가 자동화 API에서 제공되는 모든 빌딩 블록을 사용하여 복잡한 자동화를 구성할 수 있는 개방형 자동화 편집기를 작성할 수도 있습니다.
자동화 추천
Home API는 공간에 있는 기기 유형과 같은 요소를 기반으로 Structure의 자동화를 제안할 수 있습니다.
자동화 추천은 AutomationSuggestion 클래스로 표시됩니다.
Structure 인터페이스는 자동화 추천 컬렉션을 반환하는 suggestions() 함수를 제공하는 HasSuggestions 인터페이스를 포함합니다.
likeSuggestion() 및 dislikeSuggestion() 메서드는 사용자가 탭하여 의견을 제공할 수 있는 및 UI 컨트롤에 연결하기 위한 것입니다.
세 번째 방법인 clearSuggestionFeedback()을 사용하면 사용자가 추천 자동화에 대한 의견을 삭제할 수 있습니다.
사용자 의견은 향후 추천에 영향을 미칩니다.
이 예에서는 Structure에 사용할 수 있는 자동화 추천을 가져오고, 추천 ID를 추출하고, likeSuggestion(), clearSuggestionFeedback(), dislikeSuggestion()를 사용하여 사용자 의견을 기록하는 방법을 보여줍니다.
import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.google.home.Structure
import kotlinx.coroutines.launch
class AutomationSuggestionsViewModel(private val structure: Structure) : ViewModel() {
fun loadAndGiveFeedback() {
viewModelScope.launch {
// 1. Fetch suggestions from structure
val suggestions = structure.suggestions()
val firstSuggestion = suggestions.firstOrNull() ?: return@launch
// Extract string suggestion ID
val suggestionId: String = firstSuggestion.id.id
// 2. Like the suggestion (thumbs up)
val liked = structure.likeSuggestion(suggestionId)
// 3. Clear previous feedback if the user toggled it off
if (liked) {
structure.clearSuggestionFeedback(suggestionId)
}
// 4. Dislike the suggestion (thumbs down)
structure.dislikeSuggestion(suggestionId)
}
}
}
동적 명령어 매개변수
동적 명령 매개변수를 사용하면 개발자가 정적 상수 값에만 의존하지 않고 런타임에 동적으로 확인되는 작업 매개변수를 구성할 수 있습니다. 이를 통해 두 가지 기본 기능이 지원됩니다.
- 시작 조건 (예: 이벤트 페이로드) 또는 상태 리더 노드, 자동화 흐름 내에 선언된 로컬 변수에서 속성 값을 전달하는 참조입니다.
- 런타임 동적 값 (예: 이벤트 속성 또는 상태 값)을 캡처하고 동적 값을 명령어 매개변수에 직접 전달하는 표현식
사용 사례
다중 누르기 이벤트를 조광 가능한 조명에 전송하는 실제 로터리 스위치를 바인딩합니다. 클릭수는 런타임에 LevelControl 단계 명령에 전달되는 동적 가치입니다.
동적 매개변수의 작동 방식
Android의 자동화 DSL에서 명령 매개변수는 정적 상수 값 대신 Expression 또는 Reference 인스턴스를 직접 허용합니다. DSL은 자동화를 구성할 때 이를 Parameter 정의로 캡슐화합니다.
유효성 검사 규칙
동적 명령어 매개변수는 다음 유효성 검사 제약 조건을 따릅니다.
- 동적 매개변수는 검색 중에 구조적으로 유효한 것으로 간주됩니다. 검색 API는 정적 인수에 대한 구체적인 값 제약 조건만 평가하기 때문입니다.
- 참조 또는 표현식 노드는 다운스트림 명령 작업에서 참조되기 전에 자동화 그래프의 업스트림에 표시되어야 합니다.
Android에서 동적 명령 매개변수 사용
동적 표현식을 명령 매개변수에 직접 전달합니다.
import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.fieldSelect
import com.google.home.automation.sequential
import com.google.home.automation.starter
import com.google.home.matter.standard.DimmableLightDevice
import com.google.home.matter.standard.DimmerSwitchDevice
import com.google.home.matter.standard.LevelControl
import com.google.home.matter.standard.LevelControlTrait.StepModeEnum
import com.google.home.matter.standard.Switch
val keypressAutomation = automation {
name = "Dynamic command parameters example"
description = "Pass starter event field directly to command"
sequential {
val dimmerStarter = starter(
dimmerSwitch,
DimmerSwitchDevice,
Switch.MultiPressOngoingEvent,
)
val clickCountExpr = fieldSelect<Switch.MultiPressOngoingEvent, UInt>(
dimmerStarter,
Switch.MultiPressOngoingEvent.EventFields.currentNumberOfPressesCounted,
)
action(dimmableLight, DimmableLightDevice) {
command(
LevelControl.step(
stepMode = StepModeEnum.Up,
stepSize = clickCountExpr,
)
)
}
}
}
또는 표현식을 로컬 변수 선언에 할당하고 나중에 흐름에서 변수를 참조합니다.
import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.fieldSelect
import com.google.home.automation.sequential
import com.google.home.automation.starter
import com.google.home.automation.variable
import com.google.home.matter.standard.DimmableLightDevice
import com.google.home.matter.standard.DimmerSwitchDevice
import com.google.home.matter.standard.LevelControl
import com.google.home.matter.standard.LevelControlTrait.StepModeEnum
import com.google.home.matter.standard.Switch
val myAutomationWithVariable = automation {
name = "Dynamic command parameters with variables"
description = "Declare a variable, assign value, and pass reference"
sequential {
val dimmerStarter = starter(
dimmerSwitch,
DimmerSwitchDevice,
Switch.MultiPressOngoingEvent,
)
val clickCountExpr = fieldSelect<Switch.MultiPressOngoingEvent, UInt>(
dimmerStarter,
Switch.MultiPressOngoingEvent.EventFields.currentNumberOfPressesCounted,
)
val clickCountVar = variable<UInt>()
clickCountVar.assign(clickCountExpr)
action(dimmableLight, DimmableLightDevice) {
command(
LevelControl.step(
stepMode = StepModeEnum.Up,
stepSize = clickCountVar,
)
)
}
}
}
유형 제약 조건
변수 및 표현식의 유형이 수신 명령 매개변수의 필수 Matter 스키마 유형 정의 (예: UShort, UByte 또는 UInt8)와 일치하는지 확인합니다.
리소스 한도
Home API의 자동화에는 다음 한도가 적용됩니다.
| 측정항목 | 한도 |
|---|---|
| 구조당 최대 자동화 수 | 64 |
| 자동화당 최대 노드 수 | 128 |
| 자동화당 최대 표현식 노드 수 | 64 |
| 구조당 최대 자동화 인스턴스 수 | 1024 |
| 구조당 개발자별 최대 자동화 인스턴스 수 | 64 |
| 구조당 일일 최대 실행 수 | 1024 |
| 개발자별, 구조별 일일 최대 실행 횟수 | 128 |