Concepts DSL

Voici une présentation des concepts fondamentaux du DSL d'automatisation.

Composants d'automatisation

Une automatisation se compose des composants de base suivants, généralement évalués dans l'ordre suivant:

1. Déclencheur : définit les conditions initiales qui activent l'automatisation, comme une modification d'un trait. Une automatisation doit comporter un déclencheur.
2. Condition : toute contrainte supplémentaire à évaluer après l'activation d'une automatisation. L'expression d'une condition doit renvoyer la valeur true pour que les actions d'une automatisation puissent être effectuées.
3. Action : commandes ou mises à jour d'état effectuées lorsque toutes les conditions sont remplies.

Par exemple, vous avez peut-être une automatisation qui atténue les lumières d'une pièce lorsque le téléviseur de cette pièce est allumé entre le coucher et le lever du soleil. Dans cet exemple :

1. Démarrage : le téléviseur a été allumé, ce qui correspond à un changement d'état d'un attribut de téléviseur.
2. Condition : l'heure actuelle de la maison où se trouve le téléviseur est évaluée.
3. Action : les lumières de la pièce où se trouve le téléviseur sont atténuées.

L'automatisation est activée lorsque le téléviseur de la pièce est allumé, mais elle ne s'exécute que si la condition "l'heure est comprise entre le coucher et le lever du soleil" est remplie.

En plus de la structure de base, les automatisations des API Home contiennent également des métadonnées, telles que le nom et la description, qui peuvent être utilisées pour les identifier pour les développeurs et les utilisateurs.

Nœuds

Dans les API Home, la structure logique d'une automatisation se compose de nodes. Les nœuds sont des unités abstraites et réutilisables qui représentent les comportements des entités ou les flux d'exécution. Chaque nœud peut avoir des variables d'entrée, ainsi que des variables de sortie pouvant être utilisées par d'autres nœuds.

Nœuds comportementaux

Les nœuds tels que les déclencheurs et les actions sont des nœuds comportementaux. Les déclencheurs activent une automatisation en fonction des modifications apportées aux attributs de l'appareil. Les actions émettent des commandes d'appareil ou mettent à jour des attributs.

Les nœuds de comportement sont généralement liés aux caractéristiques de l'appareil et à l'état des caractéristiques de sortie pour être utilisés comme entrée dans d'autres nœuds.

Nœuds du flux d'exécution

Certains nœuds représentent des flux d'exécution, tels que séquentiels et parallèles. Chacun de ces nœuds contient les nœuds de comportement qui définissent l'automatisation.

Par exemple, un flux séquentiel peut contenir des nœuds qui s'exécutent dans l'ordre séquentiel. Il s'agit généralement du déclencheur, de la condition et de l'action.

Dans un flux parallèle, plusieurs nœuds d'action peuvent s'exécuter en même temps, par exemple pour allumer plusieurs lumières en même temps. Les nœuds qui suivent un flux parallèle ne s'exécutent pas tant que toutes les branches du flux parallèle ne sont pas terminées.

Un autre type de flux d'exécution est un flux conditionnel, qui peut modifier le flux d'exécution en fonction de l'évaluation d'une expression.

Par exemple, vous avez peut-être une automatisation qui effectue une action en fonction de l'heure de la journée. Un nœud de condition vérifie l'heure de la journée, puis suit le chemin d'exécution approprié en fonction de cette évaluation.

Un flux de sélection est utile lorsque vous souhaitez que plusieurs déclencheurs puissent activer votre automatisation. Lorsque vous encapsulez deux déclencheurs ou plus dans un flux select, n'importe lequel d'eux peut activer l'automatisation.

Par exemple, vous pouvez créer une automatisation qui abaisse les volets au coucher du soleil, si la température dépasse un certain seuil ou si la luminosité dépasse un seuil. Trois déclencheurs distincts gèrent chacun de ces scénarios, et tous les trois sont encapsulés dans un flux select.

Flux imbriqués

Dans les automatisations complexes, les nœuds de flux d'exécution peuvent également être imbriqués. Par exemple, vous pouvez avoir un flux séquentiel qui exécute un flux parallèle.

Les nœuds DSL peuvent être imbriqués et combinés de différentes manières pour répondre à vos besoins spécifiques, conformément aux contraintes décrites dans le tableau suivant. La colonne "Builder" renvoie vers la documentation du compilateur avec sûreté de typage Kotlin, qui détaille ce qui est autorisé dans chaque type de nœud.

DSL d'automatisation

Dans les API Home, les automatisations sont définies à l'aide du langage spécifique au domaine (DSL) Automation. Le DSL d'automatisation est implémenté en tant que DSL Kotlin (langage spécifique au domaine), à l'aide de compilateurs Kotlin avec sûreté de typage. Il est spécifiquement conçu pour définir des modèles d'automatisation.

Lorsqu'une automatisation est compilée, les compilateurs sécurisés Kotlin génèrent des classes de données Kotlin qui sont ensuite sérialisées au format JSON de protocole de tampon, qui est utilisé pour effectuer des appels aux services d'automatisation de Google.

Le DSL d'automatisation simplifie et accélère le processus de création d'automatisations. Elle utilise nativement le même modèle de données que les caractéristiques standards Matter et les caractéristiques smart home de l'API Device.

Le DSL d'automatisation définit également la logique d'une automatisation en termes de types d'appareils abstraits, par opposition aux instances d'appareils spécifiques situées dans la maison d'un utilisateur. Il permet au développeur de fournir des paramètres d'entrée pouvant être utilisés au moment de l'exécution pour spécifier des instances d'appareils réelles, ainsi que d'autres valeurs de paramètre importantes.

La syntaxe du DSL est semblable à celle de Kotlin et est tout aussi sûre de type, mais une automatisation écrite dans le DSL Automation est plus simple et plus concise que la même automatisation écrite en Kotlin pur.

Exemple

Voici un exemple d'automatisation qui allume un appareil, écrit à l'aide du DSL d'automatisation:

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

Cette automatisation est très basique: lorsque device1, une lumière, s'allume (l'attribut onOff passe à true), la commande on() est envoyée pour allumer device2.

L'automatisation utilise un nœud sequential, ce qui indique que ses nœuds s'exécuteront dans l'ordre séquentiel.

Le nœud sequential contient des nœuds de comportement tels que starter, condition et action. La sortie du nœud starter est attribuée à une variable à utiliser dans le nœud condition.