Le API Google Home per Android forniscono un'interfaccia API unificata per consentire agli sviluppatori di interagire con lo stato delle entità nella casa di un utente. Queste entità possono descrivere dispositivi e informazioni non relative ai dispositivi associati alla struttura e alle camere di un utente.
Le API Home definiscono le seguenti entità con cui un utente può interagire:
- Le strutture rappresentano una casa che contiene stanze e dispositivi.
- Le stanze fanno parte di una struttura e contengono dispositivi.
- I dispositivi implementano tratti contenenti attributi, sono conformi ai tipi, emettono eventi e rispondono ai comandi.
- Le automazioni fanno parte di una struttura e utilizzano i metadati e i dispositivi della casa per automatizzare le attività in casa.
La Figura 1 illustra questa architettura:
I tipi di dispositivi dell'API Home possono essere supportati da Matter, uno standard aperto per la smart home, o essere un dispositivo Cloud-to-cloud nell'ecosistema Google Home. Alcuni tipi di dispositivi potrebbero incorporare funzionalità di entrambi. Per ulteriori informazioni, consulta Tipi di dispositivi supportati.
In Matter, le funzionalità dei dispositivi sono raggruppate in cluster, che nelle API Home sono rappresentati come tratti Matter standard. Le API Home supportano l'insieme standard di cluster Matter come definito nella specifica Matter corrente.
Nell'ecosistema Google Home, le funzionalità dei dispositivi sono raggruppate in base alle caratteristiche per la smart home, che nelle API Home sono rappresentate come caratteristiche per la smart home di Google. Le API Home supportano l'insieme di trait per la smart home come definito nel programma Cloud-to-cloud.
Sono disponibili anche altri tratti, come i cluster specifici del produttore e i tratti della piattaforma. Per scoprire di più, consulta la sezione Modello di dati.
Lingua
Le API Home sono scritte in Kotlin e forniscono un'interfaccia Kotlin idiomatica che utilizza Flow per gestire lo stato e l'abbonamento. Ciò offre una serie di vantaggi rispetto a un'API di abbonamento standard.
Se non lo hai già fatto, ti consigliamo di familiarizzare con la documentazione di Kotlin su coroutine, flow e Jetpack Compose:
- Sviluppare app per Android con Kotlin
- Imparare Kotlin per Android
- Coroutine Kotlin su Android. Potrebbero essere utili questi codelab specifici:
- Kotlin Flow su Android e, più specificamente, su StateFlow.
- Stato e Jetpack Compose, in particolare la funzione
collectAsStateWithLifecycle(). Questa funzione gestisce automaticamente l'iscrizione e la disiscrizione ai flussi in base al fatto che l'interfaccia utente che mostra lo stato sia effettivamente in primo piano o meno. - Se utilizzi l'API Automation, ti consigliamo di leggere l'articolo sui costruttori sicuri di tipo Kotlin per comprendere il funzionamento del DSL di automazione.
Identificatori di entità
Ogni entità nelle API Home ha un ID che rappresenta il suo identificatore principale. Questo ID è un identificatore univoco e stabile che non cambierà mai per tutta la durata dell'entità. Questo ID può essere utilizzato per memorizzare nella cache gli oggetti o verificare la parità, poiché i metadati di un'entità possono cambiare.
Consulta l'interfaccia HasId per scoprire quali entità hanno un ID.
Mappatura della terminologia
Le entità nelle API Home vengono associate ai concetti Matter e Cloud-to-cloud come segue:
| API per la casa | Matter | Cloud-to-cloud |
|---|---|---|
| Tratto | Cluster | Tratto |
| Attributo | Attributo | Attributo, stato |
| Comando | Comando | Comando |
| Evento | Evento | Risposta di follow-up, Notifica |