Principes de base du langage

Comprendre YAML

YAML est un langage courant utilisé pour spécifier la configuration logicielle. Il offre un moyen simple, clair et lisible pour représenter des informations structurées. Voici quelques éléments de base à connaître sur YAML avant de créer votre première automatisation à l'aide de l'éditeur de script. Pour en savoir plus sur YAML en général, consultez la spécification de la version 1.1.

Paires clé/valeur

Les documents YAML sont essentiellement une collection de paires clé/valeur. Dans l'exemple ci-dessous, la clé est name et la valeur est TV on lights off. La clé et la valeur sont séparées par le signe deux-points, suivi d'un espace. Ces deux caractères sont requis pour un fichier YAML correctement formaté.

name: TV on lights off

Valeurs

La valeur associée à une clé peut être aussi simple qu'une chaîne, un nombre ou une date, ou aussi complexe qu'une autre collection de paires clé/valeur.

Strings

Si une valeur de chaîne commence par l'un des caractères suivants: [, {, ", ' ou #, ou si la chaîne contient : (deux-points suivis d'espaces), il doit être placé entre guillemets.

Les guillemets simples et doubles sont acceptés, mais le guillemet fermant doit correspondre au guillemet d'ouverture.

Citations correctes :

name: 'TV on lights off'

name: "TV on lights off"

Citations incorrectes (guillemets non concordants):

name: 'TV on lights off"

Les guillemets sont facultatifs pour tous les autres types de chaînes.

Si vous avez besoin d'une chaîne multiligne, consultez la section sur les scalaires multilignes dans la section de spécification YAML.

name: "[1] TV"
name: '{1} TV'
name: '#TV'
name: '"1" TV'
name: "'1' TV"
name: "\"1\" TV"
name: "TV: bedroom"

Imbriquer des paires clé-valeur

Ici, la valeur de la clé metadata est une liste de deux paires clé/valeur (name et description):

metadata:
  name: TV on lights off
  description: Turn off lights when TV turns on

Retrait

YAML utilise des retraits pour indiquer la structure. Dans l'exemple précédent, name et description sont mis en retrait (de deux espaces) pour indiquer qu'il s'agit des enfants de la clé metadata.

La mise en retrait est stricte en YAML. Une structure enfant doit présenter un retrait plus profond que son parent, et les paires clé-valeur du même niveau doivent avoir le même retrait.

metadata:
  name:
    en: TV on lights off
  description:
    en: Turn off lights when TV turns on

Plusieurs valeurs

Si une clé donnée comporte plusieurs valeurs, chaque valeur est indiquée sur une nouvelle ligne, et chaque ligne commence par un tiret et un espace. L'exemple ci-dessous comporte deux listes:

  1. Une automatisation peut avoir plusieurs starters. Le premier déclencheur commence donc par un tiret et un espace.
  2. weekday peut avoir plusieurs valeurs. Par conséquent, chaque valeur est davantage mise en retrait et commence par un tiret et un espace.
starters:
- type: time.schedule
  at: SUNSET
  weekday:
  - MONDAY
  - THURSDAY
  state: on

Commentaires

Tout texte situé après un élément # est considéré comme un commentaire. Il est ignoré par le moteur d'automatisation.

Une ligne commençant par # est un commentaire.

Un commentaire peut apparaître sur la même ligne que le contenu du script, mais # doit être précédé d'un espace.

# This is a comment. It will be ignored.
name: chromecast #This is a TV.

Script d'automatisation

La spécification de la syntaxe du script d'automatisation est appelée schéma.

Le schéma d'automatisation définit deux structures de données:

  • Une seule paire clé-valeur est appelée champ.
  • Un ensemble de champs défini par le schéma est appelé Struct.

Struct

Le langage de script d'automatisation définit plusieurs "blocs" ou structures de données standards, appelés structures.

Prenons l'exemple du struct automation, qui définit quatre champs:

Clé Type Description

name

String

Facultatif.

Nom de l'automatisation.

Les utilisateurs ne le verront pas. Il est uniquement destiné aux développeurs.

starters

[Déclencheur]

Obligatoire.

Liste de déclencheurs.

condition

État

Facultatif.

Condition.

actions

[Action]

Obligatoire.

Liste d'actions.

La section Références fournit des définitions de schéma pour tous les objets STRUCT disponibles.

Les noms de clés sont uniques au sein d'un objet Struct donné et sont sensibles à la casse.

Les types de valeurs possibles sont les suivants:

  • Un type primitif: valeur booléenne, nombre, chaîne, heure, etc.
  • Un type Struct: une collection de champs.
  • Tableau du type de données. Le tableau est désigné par []. Par exemple, [string] est un tableau de chaînes, et [Starter] un tableau de structures de démarrage.
  • Autres types spéciaux: Entity, FieldPath.

La description de chaque champ contient des informations importantes, y compris:

  • Obligatoire ou facultatif, indiquant si le champ est obligatoire ou s'il peut être ignoré.
  • Dépendance du champ. Seuls les champs facultatifs comportent des dépendances. Cette section décrit les vérifications supplémentaires qui s'appliquent lors de l'utilisation de ce champ, telles que Utiliser le champ B uniquement si le champ A est défini ou Lorsque le champ A est utilisé, ne définissez pas le champ B ni le champ C.
  • Valeurs possibles. Par exemple, l'ensemble de valeurs limité d'un champ d'énumération de type chaîne ou une plage de nombres pouvant être utilisée dans un champ de type numérique.

Structure typée

Certains objets struct doivent fournir certaines informations. Par exemple, un struct starter peut représenter un starter basé sur une planification horaire ou un déclencheur basé sur le changement d'état de l'appareil. Chaque type de starter doit fournir un ensemble distinct de champs.

# A time schedule starter.
starter:
  type: time.schedule
  at: 10:00

# A device state change starter.
starter:
  type: device.state.OnOff
  device: TV - Living Room
  state: on
  is: true

Un starter est un Struct typé, qui est étendu par d'autres structures enfants dans le champ type, telles que time.schedule ou device.state.OnOff, pour fournir différentes fonctions. Les structures condition et action sont également saisies.

Les champs supplémentaires du Struct doivent suivre la spécification du Struct enfant (type). Par exemple, lorsque vous utilisez device.state.OnOff comme type, seuls les champs spécifiés pour ce type sont valides dans ce struct starter.

Array

En YAML, un tableau de valeurs commence par - (un tiret suivi d'un espace). Le tableau peut contenir plusieurs valeurs Struct ou plusieurs valeurs primitives. Toutefois, les valeurs du tableau doivent être du même type.

Lorsque le tableau contient un seul élément, vous pouvez omettre le tiret et l'espace:

# The starters field accepts an array of Starter Structs.
# This is the standard format.
starters:
- type: time.schedule
  at: sunset
- type: time.schedule
  at: sunrise

# The dash can be omitted if the array only has one item.
# This is also valid.
starters:
  type: time.schedule
  at: sunset

Les tableaux multidimensionnels, comme [[1, 2], [3, 4]], ne sont pas compatibles avec les scripts d'automatisation. L'analyseur de langue aplatit automatiquement un tableau multidimensionnel en un tableau à une seule dimension, dans ce cas, [1, 2, 3, 4].

# INVALID: multi-dimensional array
- - 1
  - 2
- - 3
  - 4

Primitif

Les types de données primitifs suivants sont compatibles avec le schéma de script des automatisations:

Valeur booléenne

  • true
  • false

Nombre

Nombre entier ou décimal

Chaîne

Texte brut

Il n'est pas nécessaire de placer des guillemets autour des chaînes, sauf dans des cas spécifiques.

Date

Jour et mois. Format : MM-JJ ou MM/JJ.

  • 09/01
  • 09-01

Heure

Heure de la journée. Il peut s'agir de l'heure de l'horloge ou de l'heure du soleil. Pour l'heure, vous pouvez utiliser le format AM/PM ou 24 h. Les secondes sont facultatives. Pour l'heure de l'énergie solaire, sunrise et sunset sont des mots clés et peuvent être suivis d'un décalage (en termes de durée).

  • 12:30 am
  • 13:00:01
  • sunrise/sunset
  • sunset+30min/sunset-1hour

DateTime

Année, mois, jour et heure. Un espace blanc est requis entre les parties "Date" et "Heure". Le format de date est AAAA-MM-JJ ou AAAA/MM/JJ. Le format de l'heure est identique à celui ci-dessus. Le fuseau horaire n'est pas accepté.

  • 2022/01/01 14:00
  • 2022-12-31 sunrise+30min

Jour de la semaine

  • MONDAY (ou MON)
  • TUESDAY (ou TUE)
  • WEDNESDAY (ou WED)
  • THURSDAY (ou THU)
  • FRIDAY (ou FRI)
  • SATURDAY (ou SAT)
  • SUNDAY (ou SUN)

Durée

Une durée.

  • 30min
  • 1hour
  • 20sec
  • 1hour10min20sec

Code couleur hexadécimal

Code hexadécimal à six chiffres représentant une couleur.

Il n'y a pas de # initial.

  • FFFFFF
  • B5D2A1
  • DFA100

Température

Données de température normale. Ajoutez toujours C/F pour indiquer le plan de température.

  • 20.5C
  • 90F

Température de couleur

Température de couleur en Kelvin.

  • 5000K

Dynamique

Parfois, le type de données d'une clé n'est pas fixe. Il peut s'agir de l'un des types primitifs, en fonction des valeurs d'autres champs.

Voici un exemple de champ de type de données dynamique : is. Le type réel est déterminé par les valeurs des champs type et state.

# The 'is' field accepts a number type.
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 1
# The 'is' field accepts a boolean type.
type: device.state.OnOff
device: My TV - Living Room
state: on
is: false

Entité

Format de chaîne spécial permettant d'identifier de manière unique une entité appartenant à un utilisateur, telle qu'un appareil ou une salle.

L'appareil est l'entité la plus couramment utilisée dans les automatisations. Le format de la chaîne d'entité est device name - room name.

# The device field accepts a Device Entity type.
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 1

FieldPath

Format de chaîne spécial utilisé pour localiser une donnée dans une charge utile de données. Dans l'exemple suivant, currentVolume est le chemin FieldPath pour le champ state.

# The state field accepts a FieldPath type.
starters:
  type: device.state.Volume
  device: My TV - Living Room
  state: currentVolume
  is: 5

D'autres éléments FieldPath peuvent nécessiter plusieurs niveaux pour accéder à l'élément requis. Le format diffère selon qu'il s'agit d'un déclencheur ou d'une action.

Les déclencheurs utilisent une notation par points, le tracé complet se trouvant dans le même champ. Cette opération est principalement effectuée à des fins de comparaison dans la logique de démarrage. Par exemple, pour utiliser la température des couleurs comme déclencheur, vous devez utiliser color.colorTemperature pour l'état:

starters:
- type: device.state.ColorSetting
  device: My Device - Room Name
  state: color.colorTemperature
  is: 2000K

Les actions, en revanche, utilisent des champs imbriqués. Pour changer la couleur d'une ampoule en bleu, au lieu d'utiliser color.name et is: blue, procédez comme suit:

actions:
- type: device.command.ColorAbsolute
  devices: My Device - Room Name
  color:
    name: blue

Variables

Vous pouvez créer une variable et lui attribuer une valeur de type primitive, une entité ou un tableau.

Vous pouvez ensuite utiliser la variable partout où le même type de données est accepté.

Les variables sont définies dans le struct input.

Entrée

Le struct input est l'endroit où vous définissez les variables d'entrée. Les variables sont généralement utilisées pour référencer:

  • un appareil ou une liste d'appareils, ou ;
  • une valeur ou une liste de valeurs.

Le struct input contient une ou plusieurs entrées, chacune définissant une seule variable d'entrée.

La clé d'un champ d'entrée input est le nom de la variable d'entrée. Le nom de la variable d'entrée peut être utilisé comme une variable globale ailleurs dans le script.

Le premier Struct de chaque entrée input est metadata, qui nomme et décrit l'entrée. Le deuxième Struct est selector, qui définit le composant d'interface utilisateur à utiliser lorsque le modèle est converti en script d'instance, lorsque les valeurs d'entrée sont configurées. Chaque selector définit le type de données de la variable d'entrée.

Dans l'exemple de struct input ci-dessous, light est un nom de variable créé par le rédacteur:

input:
  light:
    metadata:
      name: light
      description: select light
    selector:
      type: device
      supportedTypes:
      - LIGHT
      - SWITCH

Les variables définies dans le bloc input peuvent être utilisées ailleurs dans le script. Elles sont référencées en faisant précéder le nom de la variable d'un $ comme ceci: $light.

supportedTypes est une liste d'un ou de plusieurs types d'appareils pouvant être utilisés chaque fois que la variable light est référencée dans le script. Dans cet exemple, la variable light représente un éclairage ou un interrupteur. supportedTypes indique à automation script editor les appareils à suggérer pour la saisie semi-automatique et les appareils à signaler comme non applicables.