Guía de la DSL de iOS

Usa la siguiente guía para comprender cómo se pueden usar varios nodos de Automation DSL para crear una automatización.

Toda la DSL de automatización se coloca dentro de un solo nodo automation. El nodo automation forma el límite entre el contexto externo del lenguaje Swift y el contexto de DSL incorporado.

Flujo secuencial

El flujo secuencial es el tipo predeterminado de flujo de automatización.

Aquí tienes una plantilla de Automation DSL muy básica que usa un flujo secuencial que consta de un activador, una condición y una acción:

import GoogleHomeSDK
import GoogleHomeTypes

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

Esto se puede mejorar agregando nodos adicionales.

Starter

Los nodos de inicio definen las circunstancias iniciales que activan una automatización. Por ejemplo, un cambio de estado o valor. Una automatización debe tener al menos un activador; de lo contrario, fallará la validación. Para agregar más de un activador a una automatización, debes usar un nodo select.

Starter basado en el atributo de rasgo

Cuando declares un nodo de inicio basado en un atributo de rasgo, especifica lo siguiente:

• el dispositivo
• el tipo de dispositivo al que pertenece el rasgo
• el rasgo

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

El parámetro de tipo de dispositivo es obligatorio porque te permite especificar a qué tipo de dispositivo dentro de un dispositivo se dirige la automatización. Por ejemplo, un dispositivo puede estar compuesto por un FanDeviceType y un HeatingCoolingUnitDeviceType, que contienen el rasgo OnOffTrait. Si especificas el tipo de dispositivo, no hay ambigüedad sobre qué parte del dispositivo activa la automatización.

Starter basado en eventos

Cuando declares un nodo de inicio basado en un evento, especifica lo siguiente:

• el dispositivo
• el tipo de dispositivo al que pertenece el rasgo
• el evento

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

Starter basado en una estructura y un evento, con parámetros

Algunos eventos pueden tener parámetros, por lo que también deben incluirse en el activador.

Por ejemplo, este activador usa el TimeTrait's ScheduledEvent para activar la automatización a las 7:00 a.m.:

typealias TimeTrait = Google.TimeTrait

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

Starter basado en el clima

Puedes especificar las condiciones climáticas actuales o pronosticadas en un activador con el rasgo Weather:

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

Consulta Cierra las persianas si es probable que llueva en la página Ejemplo de automatizaciones.

Starter manual

Un activador manual es un tipo especial de activador que permite al usuario ejecutar la automatización de forma manual.

Cuando declares un activador manual, haz lo siguiente:

• No especifiques un rasgo ni un tipo de dispositivo.
• Proporciona un elemento de la IU que llame a Automation.execute().

Cuando colocas un activador manual en un flujo select junto con otro activador, el activador manual anula el otro activador:

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

Ten en cuenta que se evaluarán todos los nodos condition que sigan a un activador manual y que podrían bloquear la ejecución de la automatización, según la expresión condition.

Una forma de estructurar tu automatización para que los nodos condition no bloqueen una automatización que se activó con un activador manual es colocar el otro activador en un flujo secuencial separado junto con su condition:

import GoogleHomeSDK
import GoogleHomeTypes

automation (
...
) {

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

}

Haz referencia al valor de un atributo

Para usar el valor de un atributo en una expresión, usa la siguiente sintaxis.

Con un stateReader:

typealias TimeTrait = Google.TimeTrait

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

Con un starter:

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

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

Nodos y expresiones de condición

Un nodo de condición representa un punto de decisión que determina si la automatización continúa o no. Una automatización puede tener varios nodos condition. Si la expresión de algún nodo condition se evalúa como false, finaliza la ejecución de toda la automatización.

Dentro de un nodo condition, puedes combinar varios criterios de condición con varios operadores, siempre que la expresión se evalúe como un solo valor booleano. Si el valor resultante es true, se cumple la condición y la automatización continúa la ejecución del siguiente nodo. Si es false, la automatización deja de ejecutarse en ese punto.

Las expresiones se forman de manera similar a las expresiones en Swift y pueden contener valores primitivos, como números, caracteres, cadenas y booleanos, así como valores de enumeración. Agrupar subexpresiones con paréntesis te permite controlar el orden en que se evalúan.

Este es un ejemplo de una condition que combina varias subexpresiones en una sola expresión:

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

Puedes hacer referencia al valor de un rasgo al que se accede a través de un activador:

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

La otra forma de hacer referencia a los valores de los atributos de rasgo en un nodo condition es con un nodo stateReader.

Para ello, primero captura el valor del atributo de rasgo en un nodo stateReader. Un stateReader toma la structure y el rasgo como argumentos:

typealias ActivatedCarbonFilterMonitoringTrait = Matter.ActivatedCarbonFilterMonitoringTrait

let filterMonitoringState = stateReader(structure, ActivatedCarbonFilterMonitoringTrait.self)

Luego, haz referencia al stateReader en el nodo condition:

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

Con operadores de comparación y lógicos, se pueden usar varios stateReaders en un nodo 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)
}

Duración de la condición

Además de una expresión booleana en una condición, puedes especificar un período durante el cual la expresión debe ser verdadera para ejecutar la automatización. Por ejemplo, puedes definir una condición que se active solo si una luz está encendida durante diez minutos.

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

La duración puede oscilar entre uno y 30 minutos.

Nodos de acción

El nodo de acción es donde se realiza el trabajo de la automatización. En este ejemplo, la acción invoca el AssistantBroadcastTrait's broadcast() comando:

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