Conceitos de DSL do Android

Esta é uma visão geral dos conceitos fundamentais da DSL de automação no Android.

Componentes de automação

Uma automação consiste nos seguintes componentes básicos, normalmente avaliados nesta ordem:

1. Ativação : define as condições iniciais que ativam a automação, como uma mudança em uma característica. Uma automação precisa ter uma ativação.
2. Condição : quaisquer restrições adicionais a serem avaliadas depois que uma automação for ativada. A expressão em uma condição precisa ser avaliada como true para que as ações de uma automação prossigam.
3. Ação : comandos ou atualizações de estado que são realizados quando todas as condições foram atendidas.

Por exemplo, talvez você tenha uma automação que escurece as luzes de um ambiente quando a TV desse ambiente é ligada entre o pôr do sol e o nascer do sol. Neste exemplo:

1. Ativação : a TV foi ligada, o que é uma mudança de estado em uma característica da TV.
2. Condição: o horário atual da casa em que a TV está é avaliado.
3. Ação : as luzes do mesmo ambiente da TV são escurecidas.

A automação seria ativada quando a TV no ambiente fosse ligada, mas a automação só seria executada se a condição de "o horário está entre o pôr do sol e o nascer do sol" fosse atendida.

Além da estrutura básica, as automações nas APIs Home também contêm metadados, como nome e descrição, que podem ser usados para identificar elas para desenvolvedores e usuários.

Nós

Nas APIs Home, a estrutura lógica de uma automação consiste em nós. Os nós são unidades abstratas e reutilizáveis que representam comportamentos de entidades ou fluxos de execução. Cada nó pode ter variáveis de entrada, bem como variáveis de saída que podem ser consumidas por outros nós.

Nós comportamentais

Nós como ativações e ações são nós comportamentais. As ativações ativam uma automação com base em mudanças de atributos do dispositivo. As ações emitem comandos de dispositivo ou atualizam atributos.

Os nós comportamentais geralmente estão vinculados a características do dispositivo e ao estado da característica de saída para uso como entrada em outros nós.

Nós de fluxo de execução

Alguns nós representam fluxos de execução, como sequenciais e paralelos. Cada um desses nós contém os nós comportamentais que definem a automação.

Por exemplo, um fluxo sequencial pode conter nós que são executados em ordem sequencial. Normalmente, eles seriam ativação, condição e ação.

Um fluxo paralelo pode ter vários nós de ação sendo executados ao mesmo tempo, como acender várias luzes ao mesmo tempo. Os nós que seguem um fluxo paralelo não serão executados até que todas as ramificações do fluxo paralelo sejam concluídas.

Outro tipo de fluxo de execução é um fluxo de condição, que pode mudar o fluxo de execução com base na avaliação de uma expressão.

Por exemplo, talvez você tenha uma automação que realiza uma ação com base no horário. Um nó de condição verifica o horário do dia e segue o caminho de execução apropriado com base nessa avaliação.

Um fluxo de seleção é útil quando você quer ter mais de uma ativação que possa ativar sua automação. Quando você inclui duas ou mais ativações em um fluxo select, qualquer uma delas pode ativar a automação.

Por exemplo, você pode escrever uma automação que abaixa as persianas ao pôr do sol, se a temperatura subir acima de um determinado limite ou se o brilho exceder um limite. Três ativações separadas processam cada um desses cenários, e todas as três seriam incluídas em um fluxo select.

Fluxos aninhados

Em automações complexas, os nós de fluxo de execução também podem ser aninhados. Por exemplo, você pode ter um fluxo sequencial que executa um fluxo paralelo.

Os nós da DSL podem ser aninhados e combinados de várias maneiras para atender às suas necessidades específicas, de acordo com as restrições descritas na tabela a seguir. A coluna "Builder" vincula à documentação do builder com segurança de tipo do Kotlin, que detalha o que é permitido para uso em cada tipo de nó.

DSL de automação

Nas APIs Home, as automações são definidas usando a DSL de automação (linguagem específica do domínio). A DSL de automação é implementada como uma DSL do Kotlin (linguagem específica do domínio), usando builders com segurança de tipo do Kotlin e foi projetada especificamente para definir modelos de automação.

Quando uma automação é compilada, os builders com segurança de tipo do Kotlin geram classes de dados do Kotlin que são serializadas para JSON de buffer de protocolo, que é usado para fazer chamadas aos serviços de automação do Google.

A DSL de automação simplifica e agiliza o processo de criação de automações. Ela usa nativamente o mesmo modelo de dados de Matter características padrão e smart home características apresentadas na API Device.

A DSL de automação também define a lógica de uma automação em termos de tipos de dispositivos abstratos, em vez de instâncias de dispositivos específicos localizados na casa de um usuário. Ela permite que o desenvolvedor forneça parâmetros de entrada que podem ser usados no ambiente de execução para especificar instâncias de dispositivos reais, bem como outros valores de parâmetros importantes.

A sintaxe da DSL é semelhante à do Kotlin e é igualmente segura, mas uma automação escrita na DSL de automação é mais simples e concisa do que a mesma automação escrita em Kotlin puro.

Exemplo

A seguir, um exemplo de automação que liga um dispositivo, escrito usando a DSL de automação:

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()) }
  }
}

Essa automação é muito básica: quando device1, uma luz, é ligada (o atributo onOff muda para true), ela envia o comando on() para ligar device2.

A automação usa um nó sequential, que indica que os nós serão executados em ordem sequencial.

Dentro do nó sequential, há nós comportamentais, como starter, condition e action. A saída do nó starter é atribuída a uma variável para uso no nó condition.