Guia de DSL para iOS

Use o guia a seguir para entender como vários nós da DSL de automação podem ser usados para criar uma automação.

Toda a DSL de automação é colocada em um único nó automation. O nó automation forma o limite entre o contexto da linguagem Swift externa e o contexto da DSL incorporada.

Fluxo sequencial

O fluxo sequencial é o tipo padrão de fluxo de automação.

Confira um modelo de DSL de automação muito básico que usa um fluxo sequencial composto por um starter, uma condição e uma ação:

import GoogleHomeSDK
import GoogleHomeTypes

automation (
...
) {
  starter(...)
  condition {...}
  action {...}
}

Isso pode ser refinado com a adição de outros nós.

Starter

Os nós de starter definem as circunstâncias iniciais que ativam uma automação. Por exemplo, uma mudança no estado ou valor. Uma automação precisa ter pelo menos um starter. Caso contrário, a validação vai falhar. Para adicionar mais de um starter a uma automação, use um nó select.

Starter com base no atributo de característica

Ao declarar um nó de starter com base em um atributo de característica, especifique:

• o dispositivo
• o tipo de dispositivo a que a característica pertence
• a característica

starter(
  thermostat,
  Matter.TemperatureSensorDeviceType.self,
  Matter.TemperatureMeasurementTrait.self
)

O parâmetro de tipo de dispositivo é obrigatório porque permite especificar qual tipo de dispositivo dentro de um dispositivo a automação aborda. Por exemplo, um dispositivo pode ser composto por um FanDeviceType e um HeatingCoolingUnitDeviceType, ambos contendo a OnOffTrait característica. Ao especificar o tipo de dispositivo, não há ambiguidade sobre qual parte do dispositivo aciona a automação.

Starter com base em eventos

Ao declarar um nó de starter com base em um evento, especifique:

• o dispositivo
• o tipo de dispositivo a que a característica pertence
• o evento

starter(
  doorbell,
  Google.GoogleDoorbellDeviceType.self,
  Google.DoorbellPressTrait.DoorbellPressedEvent
)

Starter com base em uma estrutura e um evento, com parâmetros

Alguns eventos podem ter parâmetros. Portanto, eles também precisam ser incluídos no starter.

Por exemplo, este starter usa o TimeTrait's ScheduledEvent para ativar a automação às 7h:

typealias TimeTrait = Google.TimeTrait

let earlyMorning = starter(
  structure,
  TimeTrait.ScheduledEvent.self
) {
  TimeTrait.ScheduledEvent.clockTime(TimeOfDay(hours: 7, minutes: 0))
}

Starter com base no clima

É possível especificar condições climáticas atuais ou previstas em um starter usando a característica de clima:

let weatherState = starter<_>(structure, trait = Weather)

Consulte Fechar as persianas se houver probabilidade de chuva na página de automações de exemplo.

Starter manual

Um starter manual é um tipo especial de starter que permite ao usuário executar a automação manualmente.

Ao declarar um starter manual:

• Não especifique uma característica ou um tipo de dispositivo.
• Forneça um elemento da interface que chame Automation.execute().

Ao colocar um starter manual em um fluxo select com outro starter, o starter manual substitui o outro:

select {
  manualStarter()
  starter(
    thermostat,
    Matter.TemperatureSensorDeviceType.self,
    Matter.TemperatureMeasurementTrait.self
  )
}

Observe que todos os nós condition que seguem um starter manual serão avaliados e poderão bloquear a execução da automação, dependendo da expressão condition.

Uma maneira de estruturar a automação para que os nós condition não bloqueiem uma automação ativada com um starter manual é colocar o outro starter em um fluxo sequencial separado com a condition dele:

import GoogleHomeSDK
import GoogleHomeTypes

automation (
...
) {

  select {
    sequential {
      starter(...)
      condition {...}
    }
    sequential {
      manualStarter()
    }
  }
  action {...}

}

Referenciar o valor de um atributo

Para usar o valor de um atributo em uma expressão, use a sintaxe a seguir.

Com um stateReader:

typealias TimeTrait = Google.TimeTrait

let time = stateReader(structure, TimeTrait.self)
time
let currTime = time.currentTime

Com um starter:

typealias LaundryWasherDeviceType = Matter.LaundryWasherDeviceType
typealias OnOffTrait = Google.OnOffTrait

let starterNode = starter(device1, LaundryWasherDeviceType.self, OnOffTrait.self)
starterNode
condition {
  starterNode.onOff.equals(true)
}

Nós e expressões de condição

Um nó de condição representa um ponto de decisão que determina se a automação continua ou não. Uma automação pode ter vários nós condition. Se a expressão de qualquer nó condition for avaliada como false, a execução de toda a automação será encerrada.

Em um nó condition, é possível combinar vários critérios de condição usando vários operadores, desde que a expressão seja avaliada como um único valor booleano. Se o valor resultante for true, a condição será atendida e a automação continuará a execução do próximo nó. Se for false, a automação vai parar de ser executada nesse ponto.

As expressões são formadas de maneira semelhante às expressões em Swift e podem conter valores primitivos, como números, caracteres, strings e booleanos, bem como valores de enumeração. Agrupar subexpressões com parênteses permite controlar a ordem em que elas são avaliadas.

Confira um exemplo de uma condition que combina várias subexpressões em uma única expressão:

condition {
  let exp1 = starterNode.lockState.equals(.unlocked)
  let exp2 = stateReaderNode.lockState.equals(true)
  let exp3 = occupancySensingDevice.occupied.notEquals(0)
  (exp1.and(exp2)).or(exp3)
}

É possível referenciar o valor de uma característica acessada por um starter:

typealias OnOffTrait = Matter.OnOffTrait

let starterNode = starter(device, OnOffTrait.self)
starterNode
condition {
  starterNode.onOff.equals(true)
}
val starterNode = starter<_>(device, OnOff)
condition() { expression = starterNode.onOff equals true }

stateReader

A outra maneira de referenciar valores de atributos de características em um nó condition é com um nó stateReader.

Para fazer isso, primeiro capture o valor do atributo de característica em um nó stateReader. Um stateReader usa a structure e a característica como argumentos:

typealias ActivatedCarbonFilterMonitoringTrait = Matter.ActivatedCarbonFilterMonitoringTrait

let filterMonitoringState = stateReader(structure, ActivatedCarbonFilterMonitoringTrait.self)

Em seguida, referencie o stateReader no nó condition:

condition {
filterMonitoringState.changeIndication.equals(.warning)
}

Usando operadores de comparação e lógicos, vários stateReaders podem ser usados em um nó condition:

typealias ArmDisarm = Google.ArmDisarmTrait
typealias DoorLockDevice = Matter.DoorLockDeviceType
typealias DoorLock = Matter.DoorLockTrait

let armState = stateReader(doorLock, DoorLockDevice.self, ArmDisarm )
let doorLockState = stateReader(doorLock, DoorLockDevice.self, DoorLock)
armState
doorLockState
condition {
  let exp1 = armState.armState
  let exp2 = doorLockState.lockState
  exp1.and(exp2)
}

Duração da condição

Além de uma expressão booleana em uma condição, é possível especificar um período durante o qual a expressão precisa ser verdadeira para executar a automação. Por exemplo, é possível definir uma condição que é acionada somente se uma luz estiver acesa por dez minutos.

condition(for: .seconds(600)) {
lightStateReader.onOff.equals(true)
}

A duração pode variar de um a 30 minutos.

Nós de ação

O nó de ação é onde o trabalho da automação ocorre. Neste exemplo, a ação invoca o AssistantBroadcastTrait's broadcast() comando:

action(speaker, SpeakerDeviceType.self) {
  Google.AssistantBroadcastTrait.broadcast(msg: "Oven Cycle Complete")
}