Guide DSL iOS

Utilisez le guide suivant pour comprendre comment différents nœuds DSL d'automatisation peuvent être utilisés pour créer une automatisation.

Tous les DSL d'automatisation sont placés dans un seul nœud automation. Le nœud automation forme la limite entre le contexte du langage Swift externe et le contexte DSL intégré.

Flux séquentiel

Le flux séquentiel est le type de flux d'automatisation par défaut.

Voici un modèle de DSL d'automatisation très simple qui utilise un flux séquentiel composé d'un déclencheur, d'une condition et d'une action :

import GoogleHomeSDK
import GoogleHomeTypes

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

Vous pouvez affiner ce résultat en ajoutant des nœuds supplémentaires.

Starter

Les nœuds de déclencheur définissent les circonstances initiales qui activent une automatisation. Par exemple, un changement d'état ou de valeur. Une automatisation doit comporter au moins un déclencheur, sinon sa validation échouera. Pour ajouter plusieurs déclencheurs à une automatisation, vous devez utiliser un nœud select.

Démarreur basé sur l'attribut de trait

Lorsque vous déclarez un nœud de démarrage basé sur un attribut de trait, spécifiez :

• l'appareil
• Type d'appareil auquel appartient la caractéristique
• le trait

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

Le paramètre de type d'appareil est obligatoire, car il vous permet de spécifier le type d'appareil auquel l'automatisation s'adresse. Par exemple, un appareil peut être composé d'un FanDeviceType et d'un HeatingCoolingUnitDeviceType, qui contiennent tous deux le trait OnOffTrait. En spécifiant le type d'appareil, vous évitez toute ambiguïté quant à la partie de l'appareil qui déclenche l'automatisation.

Déclencheur basé sur un événement

Lorsque vous déclarez un nœud de démarrage basé sur un événement, spécifiez les éléments suivants :

• l'appareil
• Type d'appareil auquel appartient la caractéristique
• l'événement

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

Déclencheur basé sur une structure et un événement, avec des paramètres

Certains événements peuvent avoir des paramètres. Ces paramètres doivent donc également être inclus dans le starter.

Par exemple, ce déclencheur utilise le paramètre ScheduledEvent de TimeTrait pour activer l'automatisation à 7h00 :

typealias TimeTrait = Google.TimeTrait

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

Démarreur basé sur la météo

Vous pouvez spécifier les conditions météorologiques actuelles ou prévues dans un déclencheur à l'aide du trait "Météo" :

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

Consultez Fermer les stores s'il risque de pleuvoir sur la page Exemples d'automatisations.

Démarreur manuel

Un déclencheur manuel est un type spécial de déclencheur qui permet à l'utilisateur d'exécuter manuellement l'automatisation.

Lorsque vous déclarez un déclencheur manuel :

• Ne spécifiez pas de trait ni de type d'appareil.
• Fournissez un élément d'interface utilisateur qui appelle Automation.execute().

Lorsque vous placez un déclencheur manuel dans un flux select avec un autre déclencheur, le déclencheur manuel remplace l'autre déclencheur :

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

Notez que tous les nœuds condition suivant un déclencheur manuel seront évalués et pourront bloquer l'exécution de l'automatisation, en fonction de l'expression condition.

Pour structurer votre automatisation de sorte que les nœuds condition ne bloquent pas une automatisation activée avec un déclencheur manuel, vous pouvez placer l'autre déclencheur dans un flux séquentiel distinct avec son condition :

import GoogleHomeSDK
import GoogleHomeTypes

automation (
...
) {

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

}

Référencer la valeur d'un attribut

Pour utiliser la valeur d'un attribut dans une expression, utilisez la syntaxe suivante.

Avec un stateReader :

typealias TimeTrait = Google.TimeTrait

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

Avec un starter :

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

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

Nœuds et expressions de condition

Un nœud de condition représente un point de décision qui détermine si l'automatisation se poursuit ou non. Une automatisation peut comporter plusieurs nœuds condition. Si l'expression d'un nœud condition est évaluée à false, l'exécution de l'automatisation entière se termine.

Dans un nœud condition, vous pouvez combiner plusieurs critères de condition à l'aide de différents opérateurs, à condition que l'expression soit évaluée à une seule valeur booléenne. Si la valeur obtenue est true, la condition est remplie et l'automatisation continue d'exécuter le nœud suivant. Si la valeur est false, l'automatisation s'arrête à ce stade.

Les expressions sont formées de la même manière que les expressions en Swift et peuvent contenir des valeurs primitives telles que des nombres, des caractères, des chaînes et des valeurs booléennes, ainsi que des valeurs d'énumération. Le regroupement de sous-expressions entre parenthèses vous permet de contrôler l'ordre dans lequel elles sont évaluées.

Voici un exemple de condition qui combine plusieurs sous-expressions en une seule expression :

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

Vous pouvez référencer la valeur d'un trait accessible via un déclencheur :

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

L'autre façon de référencer les valeurs d'attribut de trait dans un nœud condition consiste à utiliser un nœud stateReader.

Pour ce faire, commencez par capturer la valeur de l'attribut de la caractéristique dans un nœud stateReader. Un stateReader utilise structure et la caractéristique comme arguments :

typealias ActivatedCarbonFilterMonitoringTrait = Matter.ActivatedCarbonFilterMonitoringTrait

let filterMonitoringState = stateReader(structure, ActivatedCarbonFilterMonitoringTrait.self)

Ensuite, référencez stateReader dans le nœud condition :

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

En utilisant des opérateurs de comparaison et des opérateurs logiques, plusieurs stateReaders peuvent être utilisés dans un nœud 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)
}

Durée de la condition

En plus d'une expression booléenne dans une condition, vous pouvez spécifier une période pendant laquelle l'expression doit être vraie pour exécuter l'automatisation. Par exemple, vous pouvez définir une condition qui ne se déclenche que si une lumière est allumée depuis 10 minutes.

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

La durée peut être comprise entre une et 30 minutes.

Nœuds d'action

Le nœud d'action est l'endroit où l'automatisation effectue son travail. Dans cet exemple, l'action appelle la commande broadcast() de AssistantBroadcastTrait :

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