Concepts du DSL Android

Cette page présente les concepts fondamentaux du DSL d'automatisation sur Android.

Composants d'automatisation

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

1. Déclencheur : définit les conditions initiales qui activent l'automatisation, par exemple une modification d'une caractéristique. Une automatisation doit avoir un déclencheur.
2. Condition : contraintes supplémentaires à é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 se poursuivre.
3. Action : commandes ou mises à jour d'état effectuées lorsque toutes les conditions sont remplies.

Par exemple, vous pouvez avoir 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éclencheur : le téléviseur a été allumé, ce qui correspond à un changement d'état d'une caractéristique du téléviseur.
2. Condition : l'heure actuelle du domicile où se trouve le téléviseur est évaluée.
3. Action : les lumières de la même pièce que 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 auprès des développeurs et des utilisateurs.

Nœuds

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

Nœuds de comportement

Les nœuds tels que les déclencheurs et les actions sont des nœuds de comportement. 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 de la caractéristique de sortie pour être utilisés comme entrée dans d'autres nœuds.

Nœuds de flux d'exécution

Certains nœuds représentent des flux d'exécution, tels que séquentiel et parallèle. 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 un ordre séquentiel. En règle générale, il s'agit d'un déclencheur, d'une condition et d'une action.

Un flux parallèle peut comporter plusieurs nœuds d'action qui s'exécutent en même temps, par exemple allumer plusieurs lumières simultanément. Les nœuds qui suivent un flux parallèle ne s'exécutent que lorsque toutes les branches du flux parallèle sont terminées.

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

Par exemple, vous pouvez avoir une automatisation qui effectue une action en fonction de l'heure. Un nœud de condition vérifie l'heure, 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 incluez deux déclencheurs ou plus dans un flux select, n'importe lequel d'entre eux peut activer l'automatisation.

Par exemple, vous pouvez écrire une automatisation qui baisse les stores 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 les trois sont inclus 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 "Compilateur" renvoie à la documentation du compilateur Kotlin avec sûreté de typage, qui explique en détail ce qui est autorisé pour chaque type de nœud.

DSL d'automatisation

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

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

Le DSL d'automatisation simplifie et rationalise le processus de création d'automatisations. Il utilise nativement le même modèle de données que les Matter caractéristiques standards et les smart home caractéristiques présentées dans 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 le domicile d'un utilisateur. Il permet au développeur de fournir des paramètres d'entrée qui peuvent ê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ètres importantes.

La syntaxe DSL est semblable à celle de Kotlin et est tout aussi sûre, mais une automatisation écrite dans le DSL d'automatisation 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 simple : lorsque device1, une lumière, s'allume (l'attribut onOff passe à true), elle envoie la commande on() pour allumer device2.

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

Dans le nœud sequential se trouvent 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.