L'SDK Local Home migliora l'integrazione della tua smart home con l'Assistente Google aggiungendo un percorso di distribuzione locale per il routing degli intent della smart home.
L'SDK Local Home offre due funzionalità: Local Execution e Local Query.
- Local Execution offre la possibilità di eseguire i comandi inviando intent
EXECtramite il percorso di fulfillment locale, anziché effettuare una chiamata API cloud. Ad esempio, la richiesta "Accendi la luce" potrebbe essere gestita da Local Execution. - Local Query consente di gestire le query relative allo stato del dispositivo inviando intent
QUERYtramite il percorso di fulfillment locale. Ad esempio, Local Query soddisfa la query "La luce è accesa?" senza effettuare una chiamata API Cloud.
L'SDK ti consente di scrivere un'app di fulfillment locale, utilizzando TypeScript o JavaScript, che contiene la logica di business della tua smart home. I dispositivi Google Home o Google Nest possono caricare ed eseguire la tua app on-device. La tua app comunica direttamente con gli smart device esistenti tramite Wi-Fi su una local area network (LAN) per eseguire i comandi dell'utente, tramite i protocolli esistenti.
L'integrazione dell'SDK offre miglioramenti delle prestazioni alla tua integrazione di Cloud-to-cloud, tra cui una latenza inferiore e una maggiore affidabilità. L'execution locale è supportata per tutti i tipi e i tratti dei dispositivi, ad eccezione di quelli che utilizzano la verifica utente secondaria.
Inizia a creare Prova l'esempio
Comprendi il funzionamento
Dopo aver ricevuto una risposta SYNC dal tuo fulfillment cloud, la piattaforma Local Home scansiona la local area network dell'utente utilizzando mDNS, trasmissione UDP o UPnP per rilevare gli smart device connessi all'assistente.
La piattaforma invia un intent IDENTIFY per determinare se il dispositivo è controllabile localmente, confrontando l'ID dispositivo nella risposta IDENTIFY con quelli restituiti dalla risposta SYNC precedente. Se il dispositivo rilevato è un
hub o un bridge, la piattaforma invia un intent REACHABLE_DEVICES e tratta l'
hub come dispositivo proxy per la comunicazione locale.
Quando riceve una risposta che conferma un dispositivo locale, la piattaforma stabilisce un percorso di fulfillment locale verso il dispositivo Google Home o Google Nest dell'utente e, successivamente, instrada i comandi dell'utente per il fulfillment locale.
Quando un utente attiva un'integrazione Cloud-to-cloud che ha un percorso di fulfillment locale, l'assistente invia l'intent EXECUTE o l'intent QUERY al dispositivo Google Home o Google Nest anziché al fulfillment in cloud. Il dispositivo esegue quindi l'app di fulfillment locale per elaborare l'intent.
La piattaforma Local Home non è deterministica nella scelta del dispositivo Google Home o Google Nest su cui attivare il comando. Gli intent EXECUTE e QUERY possono essere inviati tramite qualsiasi
dispositivo Google Home o Google Nest definito nella stessa struttura
Home Graph del dispositivo di destinazione.
App di fulfillment locale
L'app di fulfillment locale contiene la logica di business per elaborare gli intent inviati dalla piattaforma Local Home e accedere allo smart device tramite la local area network. Non è prevista alcuna modifica dell'hardware per integrare il fulfillment locale. L'app soddisfa le richieste di integrazione di Cloud-to-cloud inviando comandi di controllo allo smart device tramite protocolli a livello di applicazione, tra cui HTTP, TCP o UDP. Nel caso in cui il percorso di fulfillment locale non vada a buon fine, il fulfillment cloud viene utilizzato come percorso di esecuzione di riserva.
Per supportare la creazione dell'app, l'SDK Local Home fornisce queste due classi principali:
DeviceManager: fornisce metodi per comunicare con gli smart device utilizzando socket TCP, UDP o richieste HTTP.App: fornisce metodi per collegare gestori per gli intent inviati da Google dopo aver rilevato dispositivi controllabili localmente (IDENTIFY,REACHABLE_DEVICES). Questa classe esegue anche i comandi dell'utente (EXECUTE) e risponde alle query dell'utente sullo stato attuale del dispositivo (QUERY).
Durante lo sviluppo, puoi creare e testare l'app caricandola sul tuo server di hosting o sulla tua macchina di sviluppo locale. In produzione, Google ospita la tua app in un ambiente sandbox JavaScript sicuro sul dispositivo Google Home o Google Nest dell'utente.
L'API Report State non è attualmente supportata per l'evasione locale. Google si affida al tuo fulfillment in cloud per elaborare queste richieste.
Ciclo di vita dell'applicazione
L'app di fulfillment locale viene caricata on demand quando la piattaforma Local Home rileva nuovi dispositivi locali corrispondenti alla configurazione di scansione del progetto o ha pending intent da inviare relativi a un dispositivo identificato in precedenza.
I dispositivi Google Home o Google Nest hanno una memoria limitata e l'app di fulfillment locale potrebbe essere terminata in qualsiasi momento a causa della pressione sulla memoria nel sistema. Questo può accadere se l'app inizia a consumare troppa memoria o se il sistema deve fare spazio per un'altra app. La piattaforma Local Home riavvia l'app solo quando sono presenti nuovi intent da inviare e risorse di memoria sufficienti per l'esecuzione dell'app.
La piattaforma Local Home scarica l'app dopo un timeout di inattività quando l'utente
scollega il proprio account o non ci sono più dispositivi che supportano il fulfillment
locale associati al agentUserId dell'utente.
Dispositivi supportati
La piattaforma Local Home esegue l'app di fulfillment locale sui dispositivi Google Home o Google Nest supportati. La tabella seguente descrive i dispositivi supportati e il runtime utilizzato su ciascun dispositivo. Per scoprire di più sui requisiti di runtime, consulta Ambiente di esecuzione.
| Dispositivo | Tipo | Ambiente |
|---|---|---|
| Google Home | Altoparlante | Chrome |
| Google Home Mini | Altoparlante | Chrome |
| Google Home Max | Altoparlante | Chrome |
| Nest Mini | Altoparlante | Chrome |
| Nest Hub | Display | Chrome |
| Nest Hub Max | Display | Chrome |
| Nest Wifi | Router | Node.js |
| Punto | Chrome |
Ambiente di esecuzione
L'ambiente di esecuzione dell'app di fulfillment locale dipende dal tuo dispositivo. La piattaforma Local Home supporta i seguenti ambienti di runtime:
- Chrome: l'app di fulfillment locale viene eseguita nel contesto di un browser Chrome
windowcon Chrome M80 o versioni successive con supporto per ECMAScript versione ES2018. - Node.js: l'app di fulfillment locale viene eseguita come script all'interno di un processo Node.js che esegue Node v10.x LTS o versioni successive con supporto per ECMAScript versione ES2018.
Struttura del codice sorgente
Ti consigliamo di raggruppare le dipendenze in un unico file JavaScript utilizzando le configurazioni del bundler fornite dall'SDK Local Home e di pacchettizzare il codice sorgente come Immediately-invoked Function Expression (IIFE).
Percorso di implementazione
Per utilizzare l'SDK Local Home per l'integrazione della smart home, devi eseguire queste attività:
| 1 | Configura la scansione | Configura Google Home Developer Console con i parametri necessari per consentire all'assistente di rilevare i dispositivi controllabili localmente. |
| 2 | Aggiorna la risposta SYNC nel tuo fulfillment cloud | Nel tuo fulfillment in cloud, modifica il gestore delle richieste SYNC per supportare il campo
otherDeviceIds utilizzato dalla piattaforma per stabilire un percorso di fulfillment locale. In questo campo, specifica gli ID dei dispositivi che possono essere controllati localmente.
|
| 3 | Implementa l'app di fulfillment locale | Utilizza l'SDK Local Home per creare un'app JavaScript per gestire gli intent IDENTIFY,
EXECUTE e
QUERY. Per i dispositivi proxy hub o bridge, devi
gestire anche l'intent REACHABLE_DEVICES.
|
| 4 | Testa l'app ed esegui il debug | Testa l'integrazione (o esegui l'autocertificazione) utilizzando la suite di test di Google Home. |
Prima di iniziare
- Acquisisci familiarità con le nozioni di base sulla creazione di un'integrazione di Cloud-to-cloud.
- Nella Google Home Developer Console, assicurati di avere un progetto per la smart home esistente e che il collegamento degli account sia configurato.
- Assicurati di aver eseguito l'accesso con lo stesso Account Google nella Developer Console e nell'assistente sul tuo dispositivo di test.
- Per scrivere la tua app, avrai bisogno di un ambiente Node.js. Per installare Node.js e npm, è consigliato Node Version Manager.
- Per utilizzare l'ultima versione dell'SDK Local Home, devi registrare i tuoi dispositivi di test al Programma Anteprima di Cast.