DSL 개념

다음은 자동화 DSL의 기본 개념에 관한 개요입니다.

자동화 구성요소

자동화는 일반적으로 다음 순서로 평가되는 다음과 같은 기본 구성요소로 구성됩니다.

1. 시작 조건: 자동화를 활성화하는 초기 조건(예: 트레잇 변경)을 정의합니다. 자동화에는 시작 조건이 있어야 합니다.
2. 조건: 자동화가 활성화된 후 평가할 추가 제약 조건입니다. 자동화 작업이 진행되려면 조건의 표현식이 true로 평가되어야 합니다.
3. 작업: 모든 조건이 충족될 때 실행되는 명령어 또는 상태 업데이트입니다.

예를 들어 일몰과 일출 사이에 방의 TV가 켜지면 방의 조명을 어둡게 하는 자동화가 있을 수 있습니다. 이 예에서는 다음과 같이 정의됩니다.

1. Starter: TV가 켜졌습니다. 이는 TV 트레잇의 상태 변경입니다.
2. 조건: TV가 있는 홈의 현재 시간이 평가됩니다.
3. 작업: TV와 같은 방의 조명이 어두워집니다.

방의 TV가 켜지면 자동화가 활성화되지만 '시간이 일몰과 일출 사이'라는 조건이 충족되는 경우에만 자동화가 실행됩니다.

Home API의 자동화에는 기본 구조 외에도 개발자와 사용자를 위해 자동화를 식별하는 데 사용할 수 있는 이름 및 설명과 같은 메타데이터도 포함됩니다.

노드

Home API에서 자동화의 논리적 구조는 nodes로 구성됩니다. 노드는 항목 동작 또는 실행 흐름을 나타내는 추상적이고 재사용 가능한 단위입니다. 각 노드에는 입력 변수와 다른 노드에서 사용할 수 있는 출력 변수가 있을 수 있습니다.

행동 노드

시작 조건 및 작업과 같은 노드는 동작 노드입니다. 시작 조건은 기기 속성 변경사항에 따라 자동화를 활성화합니다. 작업은 기기 명령을 실행하거나 속성을 업데이트합니다.

동작 노드는 일반적으로 다른 노드에서 입력으로 사용하기 위해 기기 트레잇 및 출력 트레잇 상태에 연결됩니다.

실행 흐름 노드

일부 노드는 순차 및 병렬과 같은 실행 흐름을 나타냅니다. 이러한 각 노드에는 자동화를 정의하는 동작 노드가 포함되어 있습니다.

예를 들어 순차 흐름에는 순차적으로 실행되는 노드가 포함될 수 있습니다. 일반적으로 시작 조건, 조건, 작업이 이에 해당합니다.

병렬 흐름에는 여러 조명 켜기와 같이 동시에 실행되는 여러 작업 노드가 있을 수 있습니다. 병렬 흐름을 따르는 노드는 병렬 흐름의 모든 브랜치가 완료될 때까지 실행되지 않습니다.

다른 유형의 실행 흐름은 조건 흐름으로, 표현식의 평가를 기반으로 실행 흐름을 변경할 수 있습니다.

예를 들어 야간인지에 따라 작업을 실행하는 자동화가 있을 수 있습니다. 조건 노드는 시간을 확인한 후 평가에 따라 적절한 실행 경로를 따릅니다.

선택 흐름은 자동화를 활성화할 수 있는 시작 조건을 두 개 이상 두려는 경우에 유용합니다. select 흐름에 두 개 이상의 시작 조건을 묶으면 시작 조건 중 하나라도 자동화를 활성화할 수 있습니다.

예를 들어 일몰 시, 온도가 특정 기준점 이상으로 상승하거나 밝기가 기준점을 초과하면 블라인드를 내리는 자동화를 작성할 수 있습니다. 세 개의 별도의 시작 조건이 이러한 각 시나리오를 처리하며 세 가지 모두 select 흐름으로 래핑됩니다.

중첩된 흐름

복잡한 자동화에서는 실행 흐름 노드를 중첩할 수도 있습니다. 예를 들어 병렬 흐름을 실행하는 순차 흐름이 있을 수 있습니다.

DSL 노드는 다음 표에 설명된 제약조건에 따라 특정 요구사항을 충족하기 위해 다양한 방식으로 중첩되고 결합될 수 있습니다. 빌더 열은 각 유형의 노드에서 사용할 수 있는 항목을 자세히 설명하는 Kotlin 형식이 안전한 빌더 문서 링크입니다.

자동화 DSL

Home API에서 자동화는 자동화 DSL(도메인별 언어)을 사용하여 정의됩니다. 자동화 DSL은 Kotlin 유형 안전 빌더를 사용하여 Kotlin DSL (도메인별 언어)로 구현되며 자동화 템플릿을 정의하기 위해 특별히 설계되었습니다.

자동화가 컴파일되면 Kotlin 유형 안전 빌더가 Kotlin 데이터 클래스를 생성하고, 이 클래스는 Google의 자동화 서비스를 호출하는 데 사용되는 프로토콜 버퍼 JSON으로 직렬화됩니다.

자동화 DSL은 자동화 빌드 프로세스를 간소화하고 능률화합니다. Device API에 표시된 Matter 표준 트레잇 및 smart home 트레잇과 동일한 데이터 모델을 기본적으로 사용합니다.

또한 자동화 DSL은 사용자 홈에 있는 특정 기기 인스턴스가 아닌 추상적인 기기 유형 측면에서 자동화 로직을 정의합니다. 이를 통해 개발자는 런타임에 실제 기기 인스턴스를 지정하는 데 사용할 수 있는 입력 매개변수와 기타 중요한 매개변수 값을 제공할 수 있습니다.

DSL 문법은 Kotlin의 문법과 유사하며 동일하게 유형 안전하지만 자동화 DSL로 작성된 자동화는 순수 Kotlin으로 작성된 동일한 자동화보다 간단하고 간결합니다.

예

다음은 자동화 DSL을 사용하여 작성된 기기를 켜는 자동화의 예입니다.

val automation = automation {
  name = "MyFirstAutomation"
  description = "If light1 is on, turn on light2."
  isActive = true
  sequential {
    val onOffTrait = starter<_>(device1, OnOffLightDevice, OnOff)
    condition() { expression = onOffTrait.onOff equals true }
    action(device2, OnOffLightDevice) { command(OnOff.on()) }
  }
}

이 자동화는 매우 기본적입니다. 조명인 device1가 켜지면 (onOff 속성이 true로 변경됨) on() 명령어를 전송하여 device2를 켭니다.

자동화는 sequential 노드를 사용하며, 이는 노드가 순차적으로 실행됨을 나타냅니다.

sequential 노드 내에 starter, condition, action와 같은 동작 노드가 있습니다. starter 노드의 출력은 condition 노드에서 사용할 변수에 할당됩니다.