Progettare un'automazione

Prima di iniziare a utilizzare l'API Automation, devi progettare le automazioni.

Determina i seguenti parametri per ogni automazione:

• Le circostanze in cui l'automazione deve essere suggerita all'utente. Ad esempio, se l'utente ha appena aggiunto tre nuove luci alla sua casa, potrebbe essere interessato a una determinata automazione personalizzata per il controllo delle luci.
• I tipi di dispositivi necessari per l'automazione. Ad esempio, se l'utente ha appena aggiunto tre nuove luci alla sua casa, potrebbe essere interessato a una determinata automazione personalizzata per il controllo delle luci. Alcuni tipi di dispositivi di illuminazione sono OnOffLightDevice, ColorTemperatureLightDevice, DimmableLightDevice o ExtendedColorLightDevice.
• Quali attributi e comandi delle caratteristiche sono richiesti per l'automazione e se sono supportati dall'API Automation.
• Le caratteristiche che devono attivare l'automazione come comandi iniziali. I comandi iniziali sono discussi in Componenti dell'automazione.
• Condizioni aggiuntive che determinano se l'automazione deve essere effettivamente eseguita e quali azioni devono essere eseguite.
• Il flusso di esecuzione dell'automazione. Deve essere eseguita in sequenza o in parallelo? Hai bisogno di più percorsi logici?

Durante la progettazione, può essere utile disegnare il flusso dell'automazione, nodo per nodo, con la logica richiesta in ogni passaggio.

Dopo aver progettato un'automazione, utilizza il DSL di automazione per crearla. L'automazione che crei è essenzialmente un "modello": tutte le strutture e i dispositivi al suo interno sono segnaposto e vengono compilati con la struttura e i dispositivi specifici di ciascun utente quando "adotta" l'automazione per il proprio utilizzo.

Di seguito sono riportati diversi tipi di automazioni che un'app potrebbe creare utilizzando le API Home. Consulta la pagina Creare un'automazione per estratti di codice relativi a questi esempi.

Automazione semplice

Supponiamo che tu debba scrivere un'app che crei un'automazione per alzare le persiane alle 8:00. Per farlo, l'app ha bisogno di un elenco delle persiane (dispositivi con il tipo di dispositivo WindowCoveringDevice) presenti nella struttura che supportano le automazioni, che possono essere fornite dall'API Discovery.

Per le automazioni che devono essere eseguite in un determinato momento, devi anche assicurarti che l'utente abbia assegnato un indirizzo stradale per la struttura scelta in Google Home app (GHA), altrimenti l'automazione non conosce il fuso orario in cui verrà eseguita. L'API Discovery può aiutarti a stabilire se alla struttura è stato assegnato o meno un indirizzo.

Di conseguenza, il flusso di esecuzione sarà simile al seguente:

1. Utilizza l'API Discovery per raccogliere l'elenco dei dispositivi WindowCoveringDevice.
2. Se l'indirizzo non è compilato, comunica all'utente che deve fornire un indirizzo e interrompi l'esecuzione.
3. In caso contrario, definisci l'automazione:
   1. Avvia l'automazione alle 8:00.
   2. Per ogni tenda, chiama il comando WindowCovering upOrOpen della relativa funzionalità.

Automazione complessa

Immagina un'app che crea un'automazione che attiva le luci lampeggianti quando viene rilevato un movimento.

Una delle prime attività per implementare questa app è scoprire quali lampadine sono disponibili nella casa dell'utente utilizzando l'API Discovery. Con queste informazioni, la tua app ora può mostrare le luci disponibili e, forse, consentire all'utente di selezionare quelle che vuole far lampeggiare.

Il flusso di esecuzione:

1. Utilizzando l'API Discovery, raccogli l'elenco dei dispositivi di illuminazione presenti nella struttura, ovvero tutti i dispositivi con tipo di dispositivo OnOffLightDevice, ColorTemperatureLightDevice, DimmableLightDevice o ExtendedColorLightDevice.
2. Fornisci un modo per selezionare le luci che lampeggiano, ad esempio tramite un riquadro personalizzato delle impostazioni.
3. Definisci l'automazione:
   1. Avvia l'automazione ogni volta che qualcuno entra o esce dai locali monitorando AreaPresenceState.
   2. Se presenceState indica che la struttura è occupata, fai lampeggiare le luci scelte.

Automazione generica

Come esempio di automazione più sofisticata, puoi prendere in considerazione quella che guida l'utente nella creazione di un'automazione aperta, in base a uno o tutti i dispositivi di cui dispone in casa.

L'automazione potrebbe chiedere all'utente di selezionare una struttura.

L'automazione potrebbe quindi mostrare tutte le camere della struttura in una visualizzazione di schemi espandibile, in cui l'espansione di una stanza mostra i dispositivi al suo interno. Se espandi un dispositivo, vengono elencati i comandi iniziali e i comandi supportati dal dispositivo.

L'utente può scegliere i dispositivi, i comandi iniziali e i comandi che vuole utilizzare e l'automazione lo guiderà nella creazione di un'automazione.

Quando tutte le scelte e le decisioni dell'utente sono definitive, l'automazione viene generata e salvata nella struttura scelta.

A un livello generale, un'automazione di questo tipo dovrebbe raccogliere diversi insiemi di dati sulla casa dell'utente utilizzando l'API Structure, l'API Device e l'API Discovery.

Tabella 1: API Home e le informazioni che possono fornire

API	Informazioni
API Structure	Quali strutture sono disponibili Quali camere sono presenti nella struttura
API Device	Quali dispositivi sono presenti nella struttura scelta Dove si trovano i dispositivi (in quale stanza)
API Discovery	Quali trait sono supportati dai dispositivi Quali comandi e comandi iniziali sono disponibili per queste caratteristiche Quali vincoli esistono per i parametri di questi comandi