Écrire des automatisations avec l'éditeur de script

L'éditeur de scripts vous permet de créer vos propres automatisations pour écrire des routines de maison avancées avec Google Home pour le Web ou dans l'application Google Home. Pour écrire des automatisations à l'aide de scripts, vous devez connaître quelques notions de base sur le langage de script YAML, et savoir structurer votre script et utiliser ses composants.

L'éditeur de script est actuellement disponible en version Preview publique. Vous pouvez accéder à l'éditeur de script avec Google Home pour le Web ou dans l'application mobile Google Home une fois que vous êtes inscrit à la version Preview publique.

• Créer des automatisations avancées pour votre maison connectée avec l'éditeur de script
• Déclencheurs, conditions et actions compatibles
• Consultez notre atelier de programmation pour voir les étapes de création d'un script
• S'entraîner à écrire une automatisation et exemples de scripts

Principes de base du langage de script YAML

L'éditeur de script utilise YAML, un langage de script flexible qui vous permet de saisir ligne par ligne des instructions correspondant à ce que vous souhaitez que vos appareils fassent et à quel moment. Ces instructions sont rédigées sous la forme de paires clé-valeur.

Paires clé-valeur

Un script YAML se présente sous la forme d'une série de paires clé-valeur :

name: TV on lights off

Dans cet exemple, la clé est name (nom) et la valeur est TV on lights off (téléviseur allumé, lumières éteintes).

La clé correspond au mot clé d'un élément que vous souhaitez utiliser. Chaque clé doit être unique, mais leur ordre n'a pas d'importance. Chaque paire clé-valeur commence sur une nouvelle ligne.

La valeur associée à une clé peut prendre plusieurs formes différentes.

Types de données

actions:
  device: Light B - Living room
  state: on

weekdays:
- MONDAY
- THURSDAY

- type: time.schedule
  at: 10:00 am
  weekdays:
  - MONDAY
  - THURSDAY
- type: time.schedule
  at: SUNSET
  weekdays:
  - MONDAY
  - THURSDAY

Syntaxe du langage YAML

Lorsque vous écrivez des scripts pour vos routines, utilisez ces concepts de mise en forme :

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

weekdays:
- MONDAY
- THURSDAY

Modèle d'éditeur de script

Lorsque vous créez une automatisation, l'éditeur de script vous fournit un modèle vide pour écrire votre script. La structure du modèle est la suivante :

Le modèle comprend deux blocs principaux : les métadonnées et les automatisations. Le bloc d'automatisations comprend à son tour des sections pour les déclencheurs, les conditions et les actions.

Blocs de métadonnées et d'automatisations

Le modèle de l'éditeur de script contient deux blocs ou clés parentes de premier niveau : metadata (métadonnées) et automations (automatisations).

Le bloc metadata contient le nom et la description de votre automatisation. Il ne sert qu'à identifier celle-ci.

metadata:
  name: TV time
  description: When TV is on, turn on lights

Le bloc automations est le cœur de votre script d'automatisation. C'est là que vous définissez le comportement de votre automatisation à l'aide de déclencheurs, de conditions et d'actions.

automations:
  starters:
    # e.g. Motion detected
  condition:
    # e.g. Between 2 times
  actions:
    # e.g. Turn on lights

Pour mieux comprendre comment utiliser l'éditeur de script, consultez notre atelier de programmation et des exemples de scripts, ou découvrez comment mettre en forme des déclencheurs, des conditions et des actions spécifiques sur le site Developer Center de Google Home.

Saisie semi-automatique

L'éditeur de script vous guide tout au long de la création de votre script en vous proposant des suggestions basées sur les déclencheurs, conditions et actions disponibles dans les cas suivants :

• Le curseur se trouve à un endroit où des options valides sont disponibles (par exemple, après - type:).
  • Vous saisissez du code avec des suggestions valides. La liste des suggestions évolue à mesure que vous tapez du texte.

Vous lancez manuellement la saisie semi-automatique à l'aide du raccourci Ctrl+Espace.

Appuyez sur Entrée pour sélectionner une suggestion dans la liste. La saisie semi-automatique remplira les champs supplémentaires en fonction de la structure que vous aurez choisie.

starters:
- device: LED lights - Living Room
- type:

starters:
- type: device.state.OnOff
- device:

Déclencheurs, conditions et actions

Les automatisations sont constituées de déclencheurs d'appareils, de conditions et d'actions. Ces composants définissent les comportements de votre automatisation.

Certains déclencheurs, conditions et actions nécessitent un type spécifique de paire clé-valeur de comparaison pour aider à exécuter la logique d'automatisation et indiquer au script ce qui doit être évalué. La valeur doit correspondre à un type de données compatible. Par exemple, l'état on (activé) d'une lumière peut être true (vrai) ou false (faux). Pour lancer l'automatisation si la lumière est allumée, écrivez ce script :

state: on
is: true

Vous trouverez ci-dessous des informations détaillées sur les différents déclencheurs, conditions et actions disponibles. Pour obtenir la liste complète des déclencheurs, conditions et actions, consultez le Developer Center de Google Home.

starters:
- type: assistant.command.OkGoogle
  eventData: query
  is: party time

starters:
- type: device.event.DoorbellPress
  device: Doorbell - Front door

starters:
- type: device.event.PersonDetection
  device: Camera - Backyard 

starters:
- type:  device.state.Volume
  device: TV - Living room
  state:  currentVolume
  greaterThan: 1
  lessThan: 10 

starters:
- type: home.state.HomePresence
  state: homePresenceMode
  is: HOME

starters:
- type: time.schedule
  at: sunrise+30min
  weekdays:
  - MON
  - TUE

metadata:
  name: Open Blinds
  description: Open blinds in the morning after motion detected
automations:
  starters:
  - type: device.event.MotionDetection
    device: Camera - Hallway
    suppressFor: 20hours
  condition:
    type: time.between
    after: 5:00 
    before: 12:00
  actions:
  - type: device.command.OpenClose
    openPercent: 100
  devices:
  - Blinds1 - Living Room
  - Blinds2 - Family Room

type: or
conditions:
- type: time.between
  before: sunrise
  after: sunset
  weekdays:
  - MON
  - TUE
- type: device.state.Volume
  device: My TV - Living Room
  state: currentVolume
  greaterThan: 1
  lessThan: 10

condition:
  type: and
  conditions:
  - type: device.state.OnOff
    device: TV - Living Room
    state: on
    is: true
  - type: time.between
    after: 6:00 pm

condition:
  type: or
  conditions:
  - type: device.state.OnOff
    device: TV - Living Room
    state: on
    is: true
  - type: time.between
    after: 6:00 pm

condition:
  type: not
  condition:
    type: time.between
    after: 6:00pm
    before: 8:00pm

condition:
  type: device.state.TemperatureSetting
  device: My Thermostat - Living Room
  state: thermostatHumidityAmbient
  greaterThan: 55

condition:
  type: home.state.HomePresence
  state: homePresenceMode
  is: HOME

condition:
  type: time.between
  before: 10am
  weekdays:
  - SAT
  - SUN

Actions

actions:
- type: assistant.command.OkGoogle
  okGoogle: Turn on living room lights
  devices: My Speaker - Room Name 

actions:
- type: assistant.command.OkGoogle
  okGoogle: Turn off all lights
  devices: My Speaker - Room Name 

actions:
- type: assistant.command.Broadcast
  devices:
  - My Speaker 1 - Room Name
  - My Speaker 2 - Room Name
  message: It’s dinner time.

actions:
  type: device.command.OnOff
  devices: TV - Living room
  on: true

actions:
- type: device.command.OnOff
  devices: Light A - Living Room
  on: true
- type: time.delay
  for: 5min
- type: device.command.OnOff
  devices: Light A - Living Room
  on: false

actions:
- type: home.command.Notification
  members:
  - Alex - [email protected]
  - Kim - [email protected]
  title: It’s movie time!
  body: Join me in the living room
 

actions:
- type: device.command.OnOff
  devices: 
    - Bedside Lamp - Bedroom
    - Ceiling Light - Bedroom
  on: true
- type: time.delay
  for: 30sec
- type: device.command.OnOff
  devices: 
    - Bedside Lamp - Bedroom
    - Ceiling Light - Bedroom
  on: false

Ressources

S'entraîner à écrire un script

Pour commencer, nous allons créer une automatisation très simple, mais couramment utilisée : "Éteindre la lumière lorsque le téléviseur s'allume".

1. Accédez à home.google.com/automations et connectez-vous à votre compte.
2. Cliquez sur Ajouter .
3. Saisissez les informations des métadonnées. Dans ce script, le nom est TV on lights off (téléviseur allumé, lumières éteintes) et la description est Turn off lights when TV turns on (Éteindre la lumière lorsque le téléviseur s'allume). Veillez à mettre en forme votre script correctement.

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

4. Pour ajouter des déclencheurs, créez une ligne, mettez-la en retrait de deux espaces ou appuyez une fois sur Tabulation, puis saisissez starters:. Mettez aussi la ligne suivante en retrait, puis saisissez dessus - type:.
   Conseil :

   • Pour créer une ligne, appuyez sur Maj  Entrée.
   • Si vous souhaitez inclure plusieurs déclencheurs, chacun d'entre eux doit commencer par un trait d'union et un espace.

metadata:
  name:  TV on lights off
  description:  Turn off lights when TV turns on
automations:
  starters:
  - type:

Remarque : L'éditeur de script vous aidera à structurer votre script en vous proposant des suggestions de saisie semi-automatique en fonction des déclencheurs disponibles. Pour sélectionner une des suggestions, utilisez les touches fléchées de votre clavier, puis appuyez sur Entrée pour l'insérer.

5. Ajoutez le déclencheur device.state. Rappelez-vous que pour utiliser un déclencheur device.state, vous avez besoin de trois clés, type, device et state, suivies d'au moins une paire clé-valeur de comparaison. L'éditeur de script vous aidera à structurer votre script en vous proposant des suggestions de saisie semi-automatique en fonction des déclencheurs, des conditions et des actions disponibles. Dans ce script :
   • Type = device.state.OnOff. Il s'agit de l'état de l'appareil qui sera évalué pour lancer notre automatisation.
   • Appareil = Chromecast - Living Room Il s'agit du nom de notre appareil tel qu'il est affiché dans l'application Google Home.
   • État = on. "On" correspond aux données de champ ou d'état prises en charge pour l'état OnOff de l'appareil.
   • Paire clé-valeur de comparaison = is: true. La valeur de cette clé de comparaison est un type de données primitif. Le script s'exécutera si le téléviseur est allumé.

     metadata:
       name: TV on lights off
       description: Turn off lights when TV turns on
     automations:
       starters:
       - type: device.state.OnOff
         device: Chromecast - Living Room
         state: on
         is: true

     À des fins de comparaison, examinons un script similaire avec un autre déclencheur. Dans le script ci-dessous, l'automatisation démarre lorsque le volume est compris entre 1 et 10, et non lorsque le téléviseur s'allume. Pour effectuer cette modification, nous avons remplacé l'état OnOff par Volume et défini l'état sur currentVolume (volume actuel) pour qu'il corresponde au nouvel attribut. Nous avons également remplacé les paires clé-valeur de comparaison par deux paires imbriquées qui créent une plage : greaterThan: 1 (supérieur à 1) et lessThan: 10 (inférieur à 10). Pour voir d'autres exemples, consultez la liste complète des déclencheurs que vous pouvez utiliser.

     metadata:
       name: TV on lights off
       description: Turn off lights when TV turns on
     automations:
       starters:
       - type: device.state.Volume
         device: Chromecast - Living Room
         state: currentVolume
         greaterThan: 1
         lessThan: 10

6. Vous pouvez cliquer sur Enregistrer à tout moment pour enregistrer votre script. Lorsque vous enregistrez un script, l'éditeur le valide automatiquement et recherche les erreurs. Les scripts non valides ne peuvent pas s'exécuter.
7. Ajoutez maintenant une action à votre script. Pour ajouter des actions, créez une ligne, mettez-la en retrait de deux espaces ou appuyez une fois sur Tabulation, puis saisissez actions:. Mettez aussi la ligne suivante en retrait, puis saisissez dessus - type.
   Conseil :

   • Pour créer une ligne, appuyez sur Maj  Entrée.
   • Si vous souhaitez inclure plusieurs actions, chacune d'entre elles doit commencer par un trait d'union et un espace.

   metadata:
     name: TV on lights off
     description: Turn off lights when TV turns on.
   automations:
     starters:
     - type: device.state.OnOff
       device: Chromecast - Living Room
       state: on
       is: true
     actions:
     - type:

8. Pour éteindre les lumières, nous utiliserons l'action device.command. Pour utiliser l'action device.command, nous allons inclure les informations suivantes :
   • Type = device.command.OnOff. Il s'agit du nom de la commande ou de l'action.
     Remarque : Les commandes peuvent avoir plusieurs commandes imbriquées sous vos appareils et chaque commande a son propre état.
   • Appareils = liste contenant Floor Lamp - Living Room (Lampadaire - Salon) et Overhead Light - Living Room (Plafonnier - Salon). Il s'agit du nom des systèmes d'éclairage tel qu'il s'affiche dans l'application Google Home. Pour inclure plusieurs systèmes d'éclairage, chaque appareil est indiqué sur une ligne distincte, avec un trait d'union au début.
   • État souhaité de la commande = on: false. Cette ligne indique à nos systèmes d'éclairage de s'éteindre.

     metadata:
       name: TV on lights off
       description: Turn off lights when TV turns on.
     automations:
       starters:
       - type: device.state.OnOff
         device: Chromecast - Living Room
         state: on
         is: true
       actions:
       - type: device.command.OnOff
         devices:
         - Floor Lamp - Living Room
         - Overhead Light - Living Room
         on: false

9. Cliquez sur Enregistrer pour enregistrer le script. S'il n'y a pas d'erreurs, le script se lance automatiquement. Dès que le téléviseur s'allume, la lumière s'éteint. Si vous n'êtes pas encore prêt à exécuter votre script, mettez-le en pause en désactivant l'option Activer.

Si vous souhaitez vous entraîner davantage, modifiez certains de vos scripts pour utiliser différents déclencheurs ou types de données, plusieurs actions ou une condition supplémentaire comme time.between. Pour en savoir plus, vous pouvez également consulter des exemples de scripts ainsi que cet atelier de programmation. Pour obtenir des informations détaillées sur les déclencheurs, les actions et les conditions, consultez le Developer Center de Google Home.

Aide concernant les scripts d'automatisation

• Pour obtenir de l'aide sur les scripts et découvrir ce sur quoi d'autres travaillent, rejoignez la communauté Google Home Automation.
• Pour que les automatisations fonctionnent, le code des scripts doit être valide. Un message s'affiche s'il y a une erreur. En savoir plus sur les erreurs et avertissements dans l'éditeur de script.
• Pour valider votre code, cliquez ou appuyez sur Valider dans l'éditeur de script, ou essayez d'enregistrer votre script. Voici quelques erreurs courantes :
  • Veillez à utiliser le bon nom d'appareil au format suivant : "Nom de l'appareil - Nom de la pièce". En cas de doute, vérifiez le nom de votre appareil dans l'application Google Home.
  • Assurez-vous que votre appareil est compatible avec la fonction souhaitée. Vous pouvez également utiliser la saisie semi-automatique pour connaître les options disponibles.
  • Veillez à inclure une action. Pour s'exécuter, une automatisation nécessite des actions.
• Si vous parvenez à enregistrer le script, mais que l'automatisation ne fonctionne pas comme prévu, vérifiez manuellement que chaque composant du script fonctionne. Par exemple, si vous avez écrit un script destiné à allumer la lumière et à modifier la luminosité au coucher du soleil, essayez d'effectuer ces tâches à l'aide d'une commande de l'Assistant pour vérifier que chaque opération fonctionne. Vous pouvez également vérifier les points suivants :
  • Votre appareil est ajouté ou associé dans l'application Google Home.
  • Votre appareil est connecté et en ligne.
  • Le nom de l'appareil, les déclencheurs, les conditions et les actions sont écrits correctement.
    Remarque : les fabricants peuvent modifier les caractéristiques des appareils lors des mises à jour, ce qui peut empêcher les scripts de fonctionner. Vous pouvez utiliser la saisie semi-automatique pour mettre à jour les scripts concernés.
  • Le retrait et la mise en forme de votre script sont corrects.
• Avec Google Home pour le Web, vous pouvez également accéder aux journaux d'automatisation  en dessous de votre script pour consulter l'historique de vos automatisations et identifier les problèmes potentiels. Découvrez les types de messages qui apparaissent dans les journaux d'automatisation..
• Utilisez la fonctionnalité expérimentale d'IA générative de l'éditeur de script pour décrire l'automatisation souhaitée. Vous obtiendrez un script que vous pourrez examiner et modifier.
• Découvrez plus en détail les principes de base des routines et comment résoudre les problèmes.
• Découvrez comment créer et modifier des scripts d'automatisation.