L'SDK Local Home migliora l'integrazione della tua smart home con l'Assistente Google aggiungendo un percorso di distribuzione locale per indirizzare gli intent per la smart home.
L'SDK consente di scrivere un'app di evasione degli ordini locale, utilizzando TypeScript o JavaScript, contenente la logica di business per la smart home. I dispositivi Google Home o Google Nest possono caricare ed eseguire l'app sul dispositivo. L'app comunica direttamente con i tuoi smart device esistenti tramite Wi-Fi su una LAN (Local Area Network) per soddisfare i comandi degli utenti sui protocolli esistenti.
L'integrazione dell'SDK offre miglioramenti delle prestazioni per l'azione della tua smart home, tra cui una minore latenza e una maggiore affidabilità. Il fulfillment locale è supportato per tutti i tipi di dispositivi e i relativi trait, ad eccezione di quelli che utilizzano la verifica utente secondaria.
Inizia a creare Prova l'esempio
Scopri come funziona
Dopo aver ricevuto una risposta SYNC
dal Cloud fulfillment, la piattaforma della casa locale analizza la rete locale 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 considera l'hub come dispositivo proxy per la comunicazione locale.
Quando riceve una risposta che conferma un dispositivo locale, la piattaforma stabilisce un percorso di evasione degli ordini locale per il dispositivo Google Home o Google Nest dell'utente, quindi instrada i comandi utente per l'evasione degli ordini locale.
Quando un utente attiva un'Azione per la smart home con un percorso di evasione degli ordini locale, l'assistente invia l'intent EXECUTE
o l'intent QUERY
al dispositivo Google Home o Google Nest anziché a Cloud fulfillment. Il dispositivo esegue quindi l'app di distribuzione locale per elaborare l'intent.
La piattaforma Local Home non è deterministica nella scelta del dispositivo Google Home o Google Nest per
attivare il comando. Gli intent EXECUTE
e QUERY
possono provenire da qualsiasi
dispositivo Google Home o Google Nest definito nella stessa struttura
Home Graph del dispositivo di destinazione.
App di evasione degli ordini locale
L'app di distribuzione locale contiene la logica di business per elaborare gli intent inviati dalla piattaforma Local Home e accedere allo smart device tramite la rete LAN. Non è prevista alcuna modifica dell'hardware per integrare l'evasione degli ordini locale. L'app soddisfa le richieste di Azione per la smart home 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 evasione degli ordini locale non vada a buon fine, l'evasione degli ordini cloud viene utilizzato come percorso di esecuzione di riserva.
Per supportare la creazione dell'app, l'SDK Local Home offre queste due classi principali:
DeviceManager
: fornisce metodi per comunicare con gli smart device utilizzando TCP, socket UDP o richieste HTTP.App
: fornisce metodi per collegare gestori per gli intent che Google invia dopo aver rilevato dispositivi controllabili a livello locale (IDENTIFY
,REACHABLE_DEVICES
). Questa classe soddisfa anche i comandi utente (EXECUTE
) e risponde alle query degli utenti sullo stato attuale del dispositivo (QUERY
).
Durante lo sviluppo, puoi creare e testare l'app caricandola sul tuo server di hosting o sulla macchina di sviluppo locale. In fase di 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 il fulfillment locale. Google si basa sul tuo fulfillment cloud per elaborare queste richieste.
Ciclo di vita dell'applicazione
L'app di distribuzione locale viene caricata on demand quando la piattaforma Local Home rileva nuovi dispositivi locali corrispondenti alla configurazione dell'analisi del progetto o ha intent in attesa di consegna relativi a un dispositivo identificato in precedenza.
I dispositivi Google Home o Google Nest hanno una memoria limitata e l'app di distribuzione locale potrebbe essere chiusa in qualsiasi momento a causa della pressione della memoria nel sistema. Questo può succedere se la tua app inizia a consumare troppa memoria o se il sistema deve fare spazio a un'altra app. La piattaforma Local Home riavvia la tua app solo quando ci sono nuovi intent da inviare e risorse di memoria sufficienti per l'esecuzione dell'app.
La piattaforma Home locale scarica la tua app dopo un timeout di inattività quando l'utente
scollega il proprio account o quando non ci sono più dispositivi che supportano il fulfillment locale
associati all'agentUserId
dell'utente.
Dispositivi supportati
La piattaforma Local Home esegue l'app di distribuzione locale sui dispositivi Google Home o Google Nest supportati. La tabella seguente descrive i dispositivi supportati e il tempo di esecuzione utilizzato su ciascun dispositivo. Per saperne 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 per la tua app di distribuzione locale dipende dal dispositivo. La piattaforma Home locale supporta i seguenti ambienti di runtime:
- Chrome: l'app di distribuzione locale viene eseguita nel contesto di un browser
Chrome
window
che esegue Chrome M80 o versioni successive con supporto per ECMAScript versione ES2018. - Node.js: l'app di evasione degli ordini locale viene eseguita come script all'interno di un processo Node.js in esecuzione 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 bundle fornite dall'SDK Local Home e di pacchettizzare il codice sorgente come Espressione di funzione a chiamata immediata (IIFE).
Percorso di implementazione
Per utilizzare l'SDK Local Home per l'integrazione con la tua smart home, devi eseguire queste attività:
1 | Configura la configurazione della scansione | Configura la console di Actions con i parametri necessari affinché l'assistente possa rilevare i dispositivi controllabili localmente. |
2 | Aggiorna la risposta SYNC in Cloud fulfillment | In Cloud fulfillment, modifica il gestore di richieste SYNC per supportare il campo
otherDeviceIds che la piattaforma utilizza per stabilire un percorso di evasione degli ordini locale. In questo campo, specifica gli ID dei dispositivi che possono essere controllati localmente.
|
3 | Implementa l'app di evasione degli ordini 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 | Testare ed eseguire il debug dell'app | Testa la tua integrazione (o l'autocertificazione) utilizzando la Test Suite di Google Home. |
Prima di iniziare
- Acquisisci familiarità con le nozioni di base per la creazione di un'azione per la smart home.
- Nella console Actions, assicurati di avere un progetto per la smart home esistente e che il collegamento dell'account sia configurato.
- Assicurati di aver eseguito l'accesso con lo stesso Account Google nella console di Actions e nell'assistente sul tuo dispositivo di test.
- Per scrivere l'app devi avere un ambiente Node.js. Per installare Node.js e npm, ti consigliamo di utilizzare Node Version Manager.
- Per utilizzare la versione più recente dell'SDK Local Home, devi registrare i dispositivi di test nel Programma Anteprima Cast.