Gescripte automatiseringen schrijven met de scripteditor

Met de scripteditor kun je je eigen automatiseringen schrijven om geavanceerde routines voor het huishouden te maken met Google Home voor het web of in de Google Home-app. Als je gescripte automatiseringen wilt schrijven, moet je wat meer weten over een aantal basisprincipes van de YAML-scripttaal, hoe je je script structureert en hoe je de componenten van je script gebruikt.

De scripteditor is op dit moment beschikbaar als Openbare preview. Je hebt toegang tot de scripteditor met Google Home voor het web of in de mobiele Google Home-app nadat je je hebt aangemeld voor Openbare preview.

• Geavanceerde smarthome-automatiseringen maken met de scripteditor
• Ondersteunde starters, voorwaarden en acties
• Ons codelab voor een stapsgewijs voorbeeld van hoe je je eerste script maakt
• Oefeningen voor het schrijven van een gescripte automatisering en voorbeeldscripts

Basisbeginselen van de YAML-scripttaal

De scripteditor gebruikt YAML, een flexibele scripttaal waarmee je regel voor regel instructies kunt invoeren voor wat je apparaten moeten doen en wanneer dit moet gebeuren. Deze instructies worden geschreven in de vorm van sleutel/waarde-paren.

Sleutel/waarde-paren

YAML wordt geschreven als een reeks sleutel/waarde-paren:

name: TV on lights off

In dit voorbeeld geldt: de sleutel = name en de waarde = TV on lights off.

De sleutel is feitelijk het zoekwoord voor een element dat je wilt gebruiken. Elke sleutel moet uniek zijn, maar de volgorde van je sleutels is niet belangrijk. Elk sleutel/waarde-paar begint op een nieuwe regel.

De waarde die aan een sleutel is gekoppeld, kan de vorm van verschillende gegevenstypen hebben.

Gegevenstypen

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

Syntaxis van de YAML-taal

Gebruik deze opmaakconcepten als je gescripte routines schrijft:

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

weekdays:
- MONDAY
- THURSDAY

De scripteditor-template

Als je een nieuwe automatisering maakt, bevat de scripteditor een lege template om je script te schrijven. Hierbij wordt de volgende structuur gebruikt:

De template is onderverdeeld in 2 hoofdblokken: metadata en automations. Automatiseringen zijn weer onderverdeeld in gedeelten voor starters, voorwaarden en acties.

Blokken voor metadata en automatiseringen

De scripteditor-template heeft 2 bovenliggende sleutels of blokken op het hoogste niveau: metadata en automations.

Het blok metadata omvat de naam en beschrijving van je automatisering. Dit wordt alleen gebruikt om je automatisering te identificeren.

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

Het blok automations vormt de kern van je automatiseringsscript. Hier definieer je het gedrag van je automatisering met starters, voorwaarden en acties.

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

Voor meer inzicht in het gebruik van de scripteditor ga je naar ons codelab, check je de voorbeeldscripts of neem je meer informatie over de indeling van afzonderlijke starters, voorwaarden en acties door in het Google Home-ontwikkelaarscentrum.

Automatisch aanvullen

Met behulp van de scripteditor kun je je script schrijven door in de volgende situaties suggesties voor automatisch aanvullen aan te bieden op basis van beschikbare starters, voorwaarden en acties:

• Als je de cursor op een plaats met geldige opties houdt. Bijvoorbeeld na - type: .
  • Terwijl je code met geldige suggesties typt. De lijst met suggesties wordt gefilterd terwijl je typt.

Je kunt automatisch aanvullen handmatig starten met de sneltoets Ctrl + spatiebalk.

Druk op Enter om een suggestie in de lijst te selecteren. Automatisch aanvullen vult extra velden in op basis van de structuur die je selecteert.

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

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

Starters, voorwaarden en acties

Automatiseringen bestaan uit apparaatstarters, voorwaarden en acties. Met deze componenten bepaal je het gedrag van je automatisering.

Sommige starters, voorwaarden en acties vereisen een specifiek type sleutel/waarde-paar om de automatiseringslogica af te ronden en je script te laten weten wat je wilt evalueren. De waarde moet een geschikt gegevenstype zijn. De status on van een lamp kan bijvoorbeeld true of false zijn. Als je de automatisering wilt starten als de lamp aanstaat, gebruik je het volgende:

state: on
is: true

Hieronder vind je meer informatie over de verschillende starters, voorwaarden en acties die beschikbaar zijn. Ga naar het Google Home-ontwikkelaarscentrum voor een volledige lijst met starters, voorwaarden en acties.

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

Acties

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

Hulpbronnen

Oefenen met een script schrijven

Voordat we aan de slag kunnen, maken we een eenvoudige maar populaire automatisering: 'Turn off the lights when the TV turns on'.

1. Open home.google.com/automations en log in op je account.
2. Klik op Nieuwe toevoegen .
3. Vul de metadata-informatie in. In dit script geldt dat de name = TV on lights off en de description = Turn off lights when TV turns on. Zorg dat je het script correct opmaakt.

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

4. Als je starters wilt toevoegen, maak je een nieuwe regel, laat je deze 2 spaties inspringen of druk je één keer op Tab en voer je starters:  in. Spring op de volgende regel weer in en voer - type: in.
   Tip:

   • Als je een nieuwe regel wilt maken, druk je op Shift Enter.
   • Als je meerdere starters wilt opnemen, moet elke starter beginnen met een koppelteken en een spatie.

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

Opmerking: De scripteditor helpt je met de structuur door suggesties voor automatisch aanvullen te leveren op basis van beschikbare starters. Als je wilt kiezen uit de suggesties, gebruik je de pijltoetsen op je toetsenbord om er een te selecteren en druk je op Enter om de suggestie in te voegen.

5. Voeg de starter device.state toe. Als je device.state-starter wilt gebruiken, gebruik je 3 sleutels: type,, device en state, gevolgd door ten minste één sleutel/waarde-paar voor vergelijking. De scripteditor helpt je met de structuur door suggesties voor automatisch aanvullen te leveren op basis van beschikbare starters, voorwaarden en acties. In dit script geldt het volgende:
   • Type = device.state.OnOff. Dit is de status van het apparaat die wordt geëvalueerd om onze automatisering te starten.
   • Device = Chromecast - Living Room. Dit is de naam van ons apparaat zoals getoond in de Google Home-app.
   • State = on. 'On' is de ondersteunde veld- of de statusinformatie voor de OnOff-status van het apparaat.
   • Het sleutel/waarde-paar voor vergelijking = is: true. De waarde voor deze vergelijkingssleutel is een primitief gegevenstype. Het script wordt uitgevoerd als de tv aanstaat.

     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

     Laten we ter vergelijking een vergelijkbaar script met een andere starter checken. In het onderstaande script wordt de automatisering gestart als het volume tussen 1 en 10 ligt in plaats van wanneer de tv aangaat. Voor deze wijziging hebben we de status OnOff vervangen door Volume en is de bijbehorende status voor het nieuwe kenmerk gewijzigd in currentVolume. We hebben ook de sleutel/waarde-paren voor vergelijking gewijzigd in 2 geneste paren die een bereik aangeven: greaterThan: 1 en lessThan: 10. Hier volgt een volledig overzicht van starters die je kunt gebruiken.

     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. Klik op Opslaan om je script op elk gewenst moment op te slaan. Als je een script opslaat, wordt je script automatisch door de scripteditor gevalideerd en op fouten gecheckt. Een ongeldig script kan niet worden uitgevoerd.
7. Voeg nu een actie aan je script toe. Als je acties wilt toevoegen, maak je een nieuwe regel, laat je deze 2 spaties inspringen of druk je één keer op Tab en voer je actions:  in. Spring de volgende regel weer in en voer - type  in.
   Tip:

   • Als je een nieuwe regel wilt maken, druk je op Shift Enter.
   • Als je meer acties wilt toevoegen, begin je elke actie met een koppelteken en een spatie.

   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. We gebruiken de actie device.command om de lampen uit te doen. We voegen de volgende informatie toe om de device.command-actie te kunnen gebruiken:
   • Type = device.command.OnOff. Dit is de naam van de opdracht of actie.
     Opmerking: Opdrachten kunnen meerdere geneste opdrachten hebben onder je apparaten, waarbij elke opdracht een eigen status heeft.
   • Devices = een lijst met Floor Lamp - Living Room en Overhead Light - Living Room. Dit zijn de namen van onze lampen, zoals ze worden getoond in de Google Home-app. Als je meerdere lampen wilt toevoegen, vermeld je elk apparaat op een afzonderlijke regel die steeds met een koppelteken begint.
   • De gewenste status van de opdracht = on: false. Deze regel vertelt ons dat onze lampen uit moeten.

     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. Klik op Opslaan om het script op te slaan. Als er geen fouten zijn, wordt je script automatisch geactiveerd: als de tv aangaat, gaan de lampen uit. Als je nog niet klaar bent om je script te laten uitvoeren, kun je het script onderbreken door Activeren uit te zetten.

Voor extra oefening raden we je aan iets aan je script te wijzigen om andere starters, gegevenstypen, meerdere acties of een extra voorwaarde zoals time.between te gebruiken. Ook kun je de voorbeeldscripts en het codelab checken voor meer informatie. Ga naar het Google Home-ontwikkelaarscentrum voor gedetailleerde informatie over starters, acties en voorwaarden.

Hulp bij gescripte automatiseringen

• Ga naar de Community voor Google Home-automatisering voor hulp met scripts en om te ontdekken waar anderen aan werken.
• Scripts moeten geldige code gebruiken, anders werken de automatiseringen niet. Als het script een fout bevat, verschijnt er een bericht. Krijg meer informatie over fouten en waarschuwingen in de scripteditor.
• Als je de code wilt valideren, klik of tik je op Valideren in de scripteditor of probeer je je script op te slaan. Dit zijn een paar veelvoorkomende fouten:
  • Zorg dat je de juiste apparaatnaam gebruikt met de indeling Device name - Room name. Als je het niet zeker weet, check je de naam van je apparaat in de Google Home-app.
  • Zorg dat je apparaat de functie ondersteunt die je wilt laten uitvoeren. Je kunt ook automatisch aanvullen gebruiken om beschikbare opties te zoeken.
  • Zorg dat je een actie in het script opneemt. Acties zijn vereist om een automatisering uit te voeren.
• Als het script wordt opgeslagen maar de automatisering niet werkt zoals verwacht, check je handmatig of elke component in je script werkt. Als je bijvoorbeeld een script hebt geschreven om een lamp aan te doen en de helderheid bij zonsondergang te wijzigen, kun je deze taken uitvoeren met een Assistent-opdracht om na te gaan of elke afzonderlijke functie werkt. Je kunt ook het volgende checken:
  • Je apparaat is toegevoegd of gekoppeld in de Google Home-app.
  • Je apparaat is verbonden en online.
  • De apparaatnaam, starters, voorwaarden en acties zijn correct geschreven.
    Opmerking: Fabrikanten kunnen apparaatkenmerken wijzigen als ze updates uitvoeren. Dit kan ertoe leiden dat scripts niet meer werken. Je kunt automatisch aanvullen gebruiken om de betreffende scripts te updaten.
  • Je script heeft de juiste inspringing en opmaak.
• Met Google Home voor het web heb je toegang tot automatiseringslogboeken  onder je script om de geschiedenis van je automatisering te checken en mogelijke problemen op te sporen. Meer informatie over de typen berichten die je in de automatiseringslogboeken ziet
• Gebruik de experimentele functie voor generatieve AI van de scripteditor om de gewenste automatisering te beschrijven. Er wordt dan een concept gemaakt van een script dat je kunt checken en bewerken.
• Meer informatie over de basisbeginselen van routines en hoe je problemen met routines oplost.
• Meer informatie over hoe je gescripte automatiseringen maakt en bewerkt.