Nozioni di base sulle lingue

Informazioni su YAML

YAML è un linguaggio popolare utilizzato per specificare la configurazione del software. Fornisce un modo chiaro e leggibile per rappresentare le informazioni strutturate. Ecco alcune nozioni di base su YAML prima di creare la tua prima automazione basata su script. Per scoprire di più su YAML in generale, consulta la specifica della versione 1.1.

Coppie chiave/valore

I documenti YAML sono fondamentalmente una raccolta di coppie chiave-valore. Nell'esempio seguente, la chiave è name e il valore è TV on lights off. Chiave e valore sono delimitati da due punti seguiti da uno spazio. Entrambi i caratteri sono necessari per un formato YAML correttamente.

name: TV on lights off

Valori

Il valore associato a una chiave può essere di base, come una stringa, un numero o una data, o complesso come un'altra raccolta di coppie chiave/valore.

Stringa

Se un valore di stringa inizia con uno dei seguenti caratteri: [, {, ", ' o #, oppure se la stringa contiene : (i due punti seguiti da spazi), deve essere racchiusa tra virgolette.

Sono accettate sia virgolette singole che doppie, ma le virgolette di chiusura devono corrispondere a quelle di apertura.

Citazioni corrette:

name: 'TV on lights off'

name: "TV on lights off"

Citazioni non corrette (citazioni non corrispondenti):

name: 'TV on lights off"

Le virgolette sono facoltative per tutti gli altri tipi di stringhe.

Se hai bisogno di una stringa su più righe, consulta la sezione delle specifiche YAML sui valori scalari multilinea.

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

Coppie chiave-valore nidificate

Qui il valore della chiave metadata è un elenco di due coppie chiave-valore (name e description):

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

Rientro

YAML usa il rientro per indicare la struttura. Nell'esempio precedente, name e description sono rientrati (di due spazi) per indicare che sono gli elementi secondari della chiave metadata.

Il rientro è rigoroso in YAML. Una struttura secondaria deve avere un rientro più ampio rispetto all'elemento padre e le coppie chiave-valore allo stesso livello devono avere lo stesso rientro.

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

Più valori

Se una determinata chiave ha più valori, ogni valore viene elencato in una nuova riga e ogni riga inizia seguita da un trattino e uno spazio. Nell'esempio seguente sono presenti due elenchi:

  1. Un'automazione può avere più starters e, di conseguenza, il primo comando iniziale inizia con un trattino e uno spazio.
  2. weekday può avere più valori e, di conseguenza, ogni valore viene ulteriormente rientrato e inizia con un trattino e uno spazio.
starters:
- type: time.schedule
  at: SUNSET
  weekday:
  - MONDAY
  - THURSDAY
  state: on

Commenti

Qualsiasi testo che segue un elemento # è considerato un commento e viene ignorato dal motore di automazione.

Una riga che inizia con # è un commento.

Un commento può essere visualizzato sulla stessa riga del contenuto dello script, ma # deve essere preceduto da uno spazio.

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

Script di automazione

La specifica per la sintassi degli script di automazioni è denominata schema.

Lo schema di automazioni definisce un paio di strutture di dati:

  • Una singola coppia chiave-valore è denominata campo.
  • Una raccolta di campi definiti dallo schema prende il nome di Struct.

Struct

Il linguaggio di scripting di automazione definisce diversi "blocchi" o strutture di dati standard, denominati Struct.

Dai un'occhiata allo struct automation, che definisce quattro campi:

Chiave Tipo Descrizione

name

Stringa

Campo facoltativo.

Nome dell'automazione.

Questa informazione non viene mostrata agli utenti, ma serve solo come riferimento per gli sviluppatori.

starters

[Comando iniziale]

Obbligatoria.

Un elenco di comandi iniziali.

condition

Condizione

Campo facoltativo.

Condizione.

actions

[Azione]

Obbligatoria.

Un elenco di azioni.

La sezione Riferimento fornisce le definizioni di schema per tutti gli Struct disponibili.

I nomi delle chiavi sono univoci all'interno di un determinato struct e sono sensibili alle maiuscole.

I tipi di valori possibili sono:

  • Un tipo primitivo: bool, numero, stringa, tempo e così via.
  • Un tipo di infrastruttura: una raccolta di campi.
  • Un array del tipo di dati. L'array è indicato con []. Ad esempio, [string] è un array di stringhe e [Starter] è un array di linee di partenza.
  • Altri tipi speciali: Entità, FieldPath.

La descrizione di ogni campo contiene informazioni importanti, tra cui:

  • Obbligatorio e Facoltativo, che indica se il campo è obbligatorio o se può essere ignorato.
  • Dipendenza campo. Solo i campi facoltativi hanno dipendenze. Descrive i controlli aggiuntivi utilizzati per questo campo, ad esempio Utilizza campo B solo se è impostato il campo A o Quando viene utilizzato il campo A, non impostare il campo B o il campo C.
  • Valori possibili. Ad esempio, l'insieme di valori limitati di un campo Enum di tipo stringa o un intervallo di numeri che può essere utilizzato in un campo di tipo numerico.

Struttura digitata

Alcuni struttura possono rappresentare i comandi iniziali in base a una programmazione temporale o a un cambiamento di stato del dispositivo. Ogni tipo di starter deve fornire un insieme distinto di campi.

# 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 è uno struct tipo, che viene esteso da altri Struct figlio nel campo type, come time.schedule o device.state.OnOff, per fornire funzioni diverse. Vengono digitati anche gli elementi condition e action.

I campi aggiuntivi nello struct devono seguire la specifica dello struct secondario (type). Ad esempio, quando utilizzi device.state.OnOff come type, solo i i campi specificati per quel tipo sono validi in quello starter Struct.

Array

In YAML, un array di valori inizia con - (un trattino seguito da uno spazio). L'array può contenere più valori Struct o più valori primitivi. Tuttavia, i valori nell'array devono essere dello stesso tipo.

Quando l'array contiene un singolo elemento, puoi omettere il trattino e lo spazio:

# 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

Gli array multidimensionali, come [[1, 2], [3, 4]], non sono supportati nello scripting automatico. Il parser linguistico suddivide automaticamente un array multidimensionale in un array a una sola dimensione, in questo caso [1, 2, 3, 4].

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

originario

Lo schema di script delle automazioni supporta i seguenti tipi di dati primitivi:

Bool
  • true
  • false

Numero

Numero intero o decimale

Stringa

Testo normale

Le stringhe non devono essere racchiuse tra virgolette, tranne in casi specifici.

Data

Mese e giorno. Il formato è MM-GG o MM/GG.

  • 09/01
  • 09-01

Tempo

Ora del giorno. Può essere l'ora dell'orologio o quella solare. Per l'ora dell'orologio, può utilizzare il formato AM/PM o 24 ore. I secondi sono facoltativi. Per l'ora solare, sunrise e sunset sono parole chiave e possono essere seguiti da un offset (in termini di durata).

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

DateTime

Anno, mese, giorno e ora del giorno. Lo spazio vuoto è obbligatorio tra la parte relativa alla data e la parte relativa all'ora. Il formato della data è AAAA-MM-GG o AAAA/MM/GG. Il formato dell'ora è uguale a [Ora](#time). Il fuso orario non è supportato.

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

Giorno feriale

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

Durata

Un periodo di tempo.

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

Un codice esadecimale a sei cifre che rappresenta un colore.

Non è presente # iniziale.

  • FFFFFF
  • B5D2A1
  • DFA100
Temperatura

Dati sulla temperatura normale. Aggiungi sempre 'C' o 'F' al valore per indicare la misurazione della temperatura.

  • 20.5C
  • 90F
ColorTemperature

Temperatura colore in Kelvin.

  • 5000K

Colore

I colori possono essere specificati in tre modi: utilizzando i tipi primitivi ColorHex o ColorTemperature, oppure il tipo composto SpectrumHSV.

SpectrumHSV

Il tipo SpectrumHSV specifica un colore mediante tre campi numerici:

  • La tonalità corrisponde alla lunghezza d'onda del colore.
  • La saturazione indica l'intensità del colore.
  • Valore indica la luminosità relativa o l'oscurità del colore.

Dinamico

A volte, il tipo di dati di una chiave non è fisso. Può essere uno dei tipi primitivi, in base ai valori di altri campi.

Un esempio di campo di tipo di dati dinamico è is. Il tipo effettivo è determinato dai valori dei campi type e 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à

Un formato stringa speciale per identificare in modo univoco un'entità di proprietà dell'utente, ad esempio dispositivo o stanza.

Il dispositivo è l'entità più comune utilizzata nelle automazioni. Il formato della stringa dell'entità è 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

Formato stringa speciale utilizzato per individuare un dato in un payload di dati. Nell'esempio seguente, currentVolume è il FieldPath per il campo state.

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

Altri FieldPath potrebbero richiedere più livelli per accedere all'elemento richiesto e il formato varia in base al comando iniziale e all'azione.

I comandi iniziali utilizzano una notazione del punto, con l'intero percorso nello stesso campo. Questo viene eseguito principalmente per scopi di confronto nella logica del comando iniziale. Ad esempio, per utilizzare la temperatura di colore come comando iniziale, utilizza color.colorTemperature per lo stato:

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

Le azioni, tuttavia, utilizzano campi nidificati. Per cambiare il colore di una lampadina in blu, anziché in color.name e is: blue, devi:

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