1. Prima di iniziare
In qualità di sviluppatore di internet of Things (IoT), puoi creare azioni per la smart home che offrono agli utenti la possibilità di controllare i propri dispositivi tramite i controlli touch nell'app Google Home e i comandi vocali con l'assistente.
Le azioni per la smart home si basano su Home Graph per fornire dati contestuali sulla casa e sui suoi dispositivi, creando una mappa logica della casa. Questo contesto offre all'assistente una comprensione più naturale delle richieste dell'utente rispetto alla sua posizione all'interno della casa. Ad esempio, Home Graph può memorizzare il concetto di un salotto che contiene più tipi di dispositivi di diversi produttori, come un termostato, una lampada, un ventilatore e un aspirapolvere.
Prerequisiti
- Guida per gli sviluppatori sull'azione per la smart home
Cosa creerai
In questo codelab, pubblicherai un servizio cloud che gestisce una lavatrice smart virtuale, quindi creerai un'azione per la smart home e la collegherai all'assistente.
Cosa imparerai a fare
- Come eseguire il deployment di un servizio cloud per la smart home
- Come collegare il tuo servizio all'assistente
- Come pubblicare su Google le modifiche allo stato dei dispositivi
Che cosa ti serve
- Un browser web, ad esempio Google Chrome.
- Un dispositivo iOS o Android su cui sia installata l'app Google Home.
- Node.js 10.16 o versioni successive
- Un account di fatturazione Google Cloud.
2. Per iniziare
Attivare Gestione attività
Per poter usare l'Assistente Google, devi condividere con Google determinati dati relativi alle attività. L'Assistente Google ha bisogno di questi dati per funzionare correttamente. Tuttavia, il requisito di condivisione dei dati non è specifico dell'SDK. Per condividere questi dati, crea un Account Google se non ne hai già uno. Puoi utilizzare qualsiasi Account Google, non è necessario che sia il tuo account sviluppatore.
Apri la pagina Gestione attività relativa all'Account Google che vuoi usare con l'assistente.
Assicurati che le seguenti opzioni di attivazione/disattivazione siano attive:
- Web e Attività nelle app: assicurati inoltre di selezionare la casella di controllo Includi la cronologia di Chrome e le attività svolte su siti, app e dispositivi che usano i servizi Google.
- Informazioni del dispositivo
- Voce e Attività audio
Creare un progetto Actions
- Vai alla Console per gli sviluppatori di Actions on Google.
- Fai clic su Nuovo progetto, inserisci un nome per il progetto e fai clic su CREA PROGETTO.
Seleziona l'app Smart home
Nella schermata Panoramica della console Actions, seleziona Smart home.
Scegli la scheda dell'esperienza Smart home, fai clic su Inizia a creare. Si aprirà la console di progetto.
Installa l'interfaccia a riga di comando di Firebase
L'interfaccia a riga di comando di Firebase (CLI) ti consente di pubblicare le app web localmente ed eseguirne il deployment su Firebase Hosting.
Per installare l'interfaccia a riga di comando, esegui questo comando npm dal terminale:
npm install -g firebase-tools
Per verificare che l'interfaccia a riga di comando sia stata installata correttamente, esegui:
firebase --version
Autorizza l'interfaccia a riga di comando di Firebase con il tuo Account Google eseguendo:
firebase login
3. Esegui l'app iniziale
Ora che hai configurato l'ambiente di sviluppo, puoi eseguire il deployment del progetto iniziale per verificare che tutto sia configurato correttamente.
Ottieni il codice sorgente
Fai clic sul link seguente per scaricare l'esempio per questo codelab sul tuo computer di sviluppo:
...oppure clonare il repository GitHub dalla riga di comando:
git clone https://github.com/google-home/smarthome-washer.git
Informazioni sul progetto
Il progetto iniziale contiene le seguenti sottodirectory:
public:Una UI frontend per controllare e monitorare facilmente lo stato della lavatrice smart.functions:Un servizio cloud completamente implementato che gestisce la lavatrice smart con Cloud Functions for Firebase e Firebase Realtime Database.
Connettersi a Firebase
Vai alla directory washer-start, quindi configura l'interfaccia a riga di comando di Firebase con il progetto Actions:
cd washer-start firebase use <project-id>
Configura un progetto Firebase
Inizializza un progetto Firebase.
firebase init
Seleziona le funzionalità dell'interfaccia a riga di comando, Realtime Database, Funzioni e la funzionalità Hosting che include Firebase Hosting.
? Which Firebase CLI features do you want to set up for this directory? Press Space to select features, then Enter to confirm your choices. ❯◉ Realtime Database: Configure a security rules file for Realtime Database and (optionally) provision default instance ◯ Firestore: Configure security rules and indexes files for Firestore ◉ Functions: Configure a Cloud Functions directory and its files ◉ Hosting: Configure files for Firebase Hosting and (optionally) set up GitHub Action deploys ◯ Hosting: Set up GitHub Action deploys ◯ Storage: Configure a security rules file for Cloud Storage ◯ Emulators: Set up local emulators for Firebase products ◯ Remote Config: Configure a template file for Remote Config ◯ Extensions: Set up an empty Extensions manifest
Verranno inizializzate le API e le funzionalità necessarie per il progetto.
Quando richiesto, inizializza Realtime Database. Puoi utilizzare la località predefinita per l'istanza di database.
? It seems like you haven't initialized Realtime Database in your project yet. Do you want to set it up? Yes ? Please choose the location for your default Realtime Database instance: us-central1
Poiché utilizzi il codice del progetto iniziale, scegli il file predefinito per le regole di sicurezza e assicurati di non sovrascrivere il file delle regole del database esistente.
? File database.rules.json already exists. Do you want to overwrite it with the Realtime Database Security Rules for <project-ID>-default-rtdb from the Firebase Console? No
Se stai reinizializzando il progetto, seleziona Sovrascrivi quando ti viene chiesto se vuoi inizializzare o sovrascrivere un codebase.
? Would you like to initialize a new codebase, or overwrite an existing one? Overwrite
Quando configuri le funzioni, devi utilizzare i file predefiniti e assicurarti di non sovrascrivere i file index.js e package.json esistenti nell'esempio del progetto.
? What language would you like to use to write Cloud Functions? JavaScript ? Do you want to use ESLint to catch probable bugs and enforce style? No ? File functions/package.json already exists. Overwrite? No ? File functions/index.js already exists. Overwrite? No
Se stai reinizializzando il progetto, seleziona No quando ti viene chiesto se vuoi inizializzare o sovrascrivere features/.gitignore.
? File functions/.gitignore already exists. Overwrite? No
? Do you want to install dependencies with npm now? Yes
Infine, configura la configurazione di Hosting in modo che utilizzi la directory public nel codice del progetto e il file index.html esistente. Seleziona No quando ti viene chiesto di utilizzare ESLint.
? What do you want to use as your public directory? public ? Configure as a single-page app (rewrite all urls to /index.html)? Yes ? Set up automatic builds and deploys with GitHub? No ? File public/index.html already exists. Overwrite? No
Se ESLint è stato abilitato per errore, esistono due metodi per disabilitarlo:
- Utilizzando la GUI, vai alla cartella
../functionsdel progetto, seleziona il file nascosto.eslintrc.jsed eliminalo. Non confonderlo con il nome simile.eslintrc.json. - Tramite la riga di comando:
cd functions rm .eslintrc.js
Per assicurarti che la configurazione di Firebase sia corretta e completa, copia il file firebase.json dalla directory washer-done alla directory washer-start, sovrascrivendo quello presente in washer-start.
Nella directory washer-start:
cp -vp ../washer-done/firebase.json .
Eseguire il deployment in Firebase
Ora che hai installato le dipendenze e configurato il progetto, puoi eseguire l'app per la prima volta.
firebase deploy
Questo è l'output della console che dovresti vedere:
... ✔ Deploy complete! Project Console: https://console.firebase.google.com/project/<project-id>/overview Hosting URL: https://<project-id>.web.app
Questo comando esegue il deployment di un'app web, insieme a diverse Cloud Functions for Firebase.
Apri Hosting URL (URL di hosting) nel browser (https://<project-id>.web.app) per visualizzare l'app web. Verrà visualizzata la seguente interfaccia:
Questa UI web rappresenta una piattaforma di terze parti per visualizzare o modificare gli stati dei dispositivi. Per iniziare a completare il database con le informazioni del dispositivo, fai clic su AGGIORNA. Non vedrai alcuna modifica nella pagina, ma lo stato attuale della lavatrice verrà memorizzato nel database.
Ora è il momento di connettere il servizio cloud di cui hai eseguito il deployment all'Assistente Google utilizzando la console Actions.
Configura il progetto della console Actions
In Panoramica > Crea la tua azione, seleziona Aggiungi azioni. Inserisci l'URL della funzione Cloud Functions che fornisce il completamento per gli intent della smart home e fai clic su Salva.
https://us-central1-<project-id>.cloudfunctions.net/smarthome
Nella scheda Sviluppo > Chiamata, aggiungi un Nome visualizzato per l'azione e fai clic su Salva. Questo nome verrà visualizzato nell'app Google Home.
Per attivare il collegamento dell'account, seleziona il menu Sviluppo > Collegamento dell'account nel riquadro di navigazione a sinistra. Utilizza queste impostazioni di collegamento dell'account:
ID client |
|
Client secret |
|
URL autorizzazione |
|
URL token |
|
Fai clic su Salva per salvare la configurazione del collegamento dell'account, quindi fai clic su Test per attivare i test sul tuo progetto.
Il sistema ti reindirizzerà al Simulatore. Se non vedi "Test ora abilitato", fai clic su Reimposta test per verificare che i test siano attivati.
Ora puoi iniziare a implementare i webhook necessari per connettere lo stato del dispositivo all'assistente.
4. Crea una lavatrice
Ora che hai configurato l'Azione, puoi aggiungere dispositivi e inviare dati. Il tuo servizio cloud deve gestire i seguenti intent:
- Un intent
SYNCsi verifica quando l'assistente vuole sapere quali dispositivi sono stati connessi dall'utente. Viene inviato al tuo servizio quando l'utente collega un account. Dovresti rispondere con un payload JSON di tutti i dispositivi dell'utente e delle loro funzionalità. - Un intent
QUERYsi verifica quando l'assistente vuole conoscere lo stato attuale di un dispositivo. Devi rispondere con un payload JSON con lo stato di ogni dispositivo richiesto. - Un intent
EXECUTEsi verifica quando l'assistente vuole controllare un dispositivo per conto di un utente. Devi rispondere con un payload JSON con lo stato di esecuzione di ogni dispositivo richiesto. - Un intent
DISCONNECTsi verifica quando l'utente scollega il proprio account dall'assistente. Dovresti interrompere l'invio all'assistente degli eventi relativi ai dispositivi di questo utente.
Nelle sezioni seguenti aggiorneremo le funzioni di cui hai eseguito il deployment in precedenza per gestire questi intent.
Aggiorna la risposta SYNC
Apri functions/index.js, che contiene il codice per rispondere alle richieste dell'assistente.
Dovrai gestire un intent SYNC restituendo i metadati e le funzionalità del dispositivo. Aggiorna il codice JSON nell'array onSync per includere le informazioni del dispositivo e i trait consigliati per una lavatrice.
index.js
app.onSync((body) => {
return {
requestId: body.requestId,
payload: {
agentUserId: USER_ID,
devices: [{
id: 'washer',
type: 'action.devices.types.WASHER',
traits: [
'action.devices.traits.OnOff',
'action.devices.traits.StartStop',
'action.devices.traits.RunCycle',
],
name: {
defaultNames: ['My Washer'],
name: 'Washer',
nicknames: ['Washer'],
},
deviceInfo: {
manufacturer: 'Acme Co',
model: 'acme-washer',
hwVersion: '1.0',
swVersion: '1.0.1',
},
willReportState: true,
attributes: {
pausable: true,
},
}],
},
};
});
Eseguire il deployment in Firebase
Esegui il deployment del fulfillment Cloud aggiornato utilizzando l'interfaccia a riga di comando di Firebase:
firebase deploy --only functions
Collegare l'Assistente Google
Per testare l'azione per la smart home, devi collegare il progetto a un Account Google. In questo modo è possibile eseguire test tramite le piattaforme dell'Assistente Google e l'app Google Home su cui è stato eseguito l'accesso allo stesso account.
- Apri le impostazioni dell'Assistente Google sullo smartphone. Tieni presente che devi aver eseguito l'accesso con lo stesso account della console.
- Vai su Assistente Google > Impostazioni > Controllo della casa (nella sezione Assistente).
- Fai clic sull'icona di ricerca in alto a destra.
- Cerca la tua app di test utilizzando il prefisso [test] per trovare la tua app di test specifica.
- Seleziona l'elemento. L'Assistente Google eseguirà quindi l'autenticazione con il tuo servizio e invierà una richiesta
SYNC, chiedendo al servizio di fornire un elenco di dispositivi per l'utente.
Apri l'app Google Home e verifica di riuscire a vedere la lavatrice.
5. Gestire comandi e query
Ora che il tuo servizio cloud segnala correttamente la lavatrice a Google, devi aggiungere la possibilità di richiedere lo stato del dispositivo e inviare comandi.
Gestire l'intent QUERY
Un intent QUERY include un insieme di dispositivi. Per ogni dispositivo dovresti rispondere indicando il suo stato attuale.
In functions/index.js, modifica il gestore QUERY per elaborare l'elenco dei dispositivi di destinazione contenuti nella richiesta di intent.
index.js
app.onQuery(async (body) => {
const {requestId} = body;
const payload = {
devices: {},
};
const queryPromises = [];
const intent = body.inputs[0];
for (const device of intent.payload.devices) {
const deviceId = device.id;
queryPromises.push(queryDevice(deviceId)
.then((data) => {
// Add response to device payload
payload.devices[deviceId] = data;
}
));
}
// Wait for all promises to resolve
await Promise.all(queryPromises);
return {
requestId: requestId,
payload: payload,
};
});
Per ogni dispositivo contenuto nella richiesta, restituisce lo stato attuale archiviato nel Realtime Database. Aggiorna le funzioni queryFirebase e queryDevice per restituire i dati di stato della lavatrice.
index.js
const queryFirebase = async (deviceId) => {
const snapshot = await firebaseRef.child(deviceId).once('value');
const snapshotVal = snapshot.val();
return {
on: snapshotVal.OnOff.on,
isPaused: snapshotVal.StartStop.isPaused,
isRunning: snapshotVal.StartStop.isRunning,
};
};
const queryDevice = async (deviceId) => {
const data = await queryFirebase(deviceId);
return {
on: data.on,
isPaused: data.isPaused,
isRunning: data.isRunning,
currentRunCycle: [{
currentCycle: 'rinse',
nextCycle: 'spin',
lang: 'en',
}],
currentTotalRemainingTime: 1212,
currentCycleRemainingTime: 301,
};
};
Gestire l'intent EXECUTE
L'intent EXECUTE gestisce i comandi per aggiornare lo stato del dispositivo. La risposta restituisce lo stato di ciascun comando, ad esempio SUCCESS, ERROR o PENDING, e il nuovo stato del dispositivo.
In functions/index.js, modifica il gestore EXECUTE affinché elabori l'elenco di trait che richiedono aggiornamenti e il set di dispositivi di destinazione per ogni comando:
index.js
app.onExecute(async (body) => {
const {requestId} = body;
// Execution results are grouped by status
const result = {
ids: [],
status: 'SUCCESS',
states: {
online: true,
},
};
const executePromises = [];
const intent = body.inputs[0];
for (const command of intent.payload.commands) {
for (const device of command.devices) {
for (const execution of command.execution) {
executePromises.push(
updateDevice(execution, device.id)
.then((data) => {
result.ids.push(device.id);
Object.assign(result.states, data);
})
.catch(() => functions.logger.error('EXECUTE', device.id)));
}
}
}
await Promise.all(executePromises);
return {
requestId: requestId,
payload: {
commands: [result],
},
};
});
Per ogni comando e dispositivo di destinazione, aggiorna i valori nel Realtime Database corrispondenti al tratto richiesto. Modifica la funzione updateDevice per aggiornare il riferimento Firebase appropriato e restituire lo stato aggiornato del dispositivo.
index.js
const updateDevice = async (execution, deviceId) => {
const {params, command} = execution;
let state; let ref;
switch (command) {
case 'action.devices.commands.OnOff':
state = {on: params.on};
ref = firebaseRef.child(deviceId).child('OnOff');
break;
case 'action.devices.commands.StartStop':
state = params.start
? {isRunning: true, isPaused: false}
: {isRunning: false, isPaused: false};
ref = firebaseRef.child(deviceId).child('StartStop');
break;
case 'action.devices.commands.PauseUnpause':
const data = await queryDevice(deviceId);
state = (data.isPaused === false && data.isRunning === false)
? {isRunning: false, isPaused: false}
: {isRunning: !params.pause, isPaused: params.pause};
ref = firebaseRef.child(deviceId).child('StartStop');
break;
}
return ref.update(state)
.then(() => state);
};
6. Testa l'azione
Dopo aver implementato tutti e tre gli intent, puoi verificare che l'azione controlli la lavatrice.
Eseguire il deployment in Firebase
Esegui il deployment del fulfillment Cloud aggiornato utilizzando l'interfaccia a riga di comando di Firebase:
firebase deploy --only functions
Prova la lavatrice
Ora puoi vedere la variazione del valore quando provi uno dei seguenti comandi vocali tramite il telefono:
"Hey Google, accendi la lavatrice."
"Hey Google, metti in pausa la lavatrice."
"Hey Google, interrompi la lavatrice."
Puoi anche vedere lo stato attuale della lavatrice ponendo delle domande.
"Hey Google, la lavatrice è accesa?"
"Hey Google, la lavatrice funziona?"
"Hey Google, a che ciclo è la lavatrice?"
Puoi visualizzare queste query e questi comandi nei log visualizzati sotto la funzione nella sezione Funzioni della Console Firebase. Per saperne di più sui log di Firebase, consulta Scrivere e visualizzare i log.
Puoi trovare queste query e questi comandi anche nella console Google Cloud accedendo a Logging > Esplora log. Per saperne di più su Google Cloud Logging, vedi Accedere ai log eventi con Cloud Logging.
7. Segnala aggiornamenti a Google
Hai integrato completamente il tuo servizio cloud con gli intent della smart home, consentendo agli utenti di controllare ed eseguire query sullo stato attuale dei loro dispositivi. Tuttavia, l'implementazione non ha ancora un modo per consentire al servizio di inviare in modo proattivo informazioni sugli eventi, ad esempio modifiche alla presenza o allo stato del dispositivo, all'assistente.
Con Richiedi sincronizzazione, puoi attivare una nuova richiesta di sincronizzazione quando gli utenti aggiungono o rimuovono dispositivi oppure quando cambiano le funzionalità dei loro dispositivi. Con lo stato del report, il servizio cloud può inviare in modo proattivo lo stato di un dispositivo a Home Graph quando gli utenti cambiano fisicamente lo stato di un dispositivo, ad esempio accendendo un interruttore della luce, oppure cambiano stato utilizzando un altro servizio.
In questa sezione, aggiungerai il codice per chiamare questi metodi dall'app web frontend.
Abilita l'API HomeGraph
L'API HomeGraph consente di archiviare ed eseguire query sui dispositivi e sul relativo stato all'interno dell'Home Graph di un utente. Per utilizzare questa API, devi prima aprire la console Google Cloud e abilitare l'API HomeGraph.
Nella console Google Cloud, assicurati di selezionare il progetto che corrisponde alle tue azioni <project-id>. Quindi, nella schermata della libreria API per l'API HomeGraph, fai clic su Abilita.
Attiva stato del report
Scrive nel Realtime Database il trigger della funzione reportstate nel progetto iniziale. Aggiorna la funzione reportstate in functions/index.js per acquisire i dati scritti nel database e pubblicarli in Home Graph tramite lo stato del report.
index.js
exports.reportstate = functions.database.ref('{deviceId}').onWrite(
async (change, context) => {
functions.logger.info('Firebase write event triggered Report State');
const snapshot = change.after.val();
const requestBody = {
requestId: 'ff36a3cc', /* Any unique ID */
agentUserId: USER_ID,
payload: {
devices: {
states: {
/* Report the current state of our washer */
[context.params.deviceId]: {
on: snapshot.OnOff.on,
isPaused: snapshot.StartStop.isPaused,
isRunning: snapshot.StartStop.isRunning,
},
},
},
},
};
const res = await homegraph.devices.reportStateAndNotification({
requestBody,
});
functions.logger.info('Report state response:', res.status, res.data);
});
Abilitare la sincronizzazione delle richieste
L'aggiornamento dell'icona nella UI web del frontend attiva la funzione requestsync nel progetto iniziale. Implementa la funzione requestsync in functions/index.js per chiamare l'API HomeGraph.
index.js
exports.requestsync = functions.https.onRequest(async (request, response) => {
response.set('Access-Control-Allow-Origin', '*');
functions.logger.info(`Request SYNC for user ${USER_ID}`);
try {
const res = await homegraph.devices.requestSync({
requestBody: {
agentUserId: USER_ID,
},
});
functions.logger.info('Request sync response:', res.status, res.data);
response.json(res.data);
} catch (err) {
functions.logger.error(err);
response.status(500).send(`Error requesting sync: ${err}`);
}
});
Eseguire il deployment in Firebase
Esegui il deployment del codice aggiornato utilizzando l'interfaccia a riga di comando di Firebase:
firebase deploy --only functions
Verificare la tua implementazione
Fai clic sul pulsante Aggiorna 
nell'interfaccia utente web e verifica che nel log della console Firebase sia presente una richiesta di sincronizzazione.
Quindi, regola gli attributi del dispositivo lavatrice nell'interfaccia utente web del frontend e fai clic su Aggiorna. Verifica di poter vedere la modifica dello stato segnalata a Google nei log della console Firebase.
8. Complimenti
Complimenti! Hai integrato correttamente l'assistente con un servizio cloud per i dispositivi utilizzando le Azioni per la smart home.
Scopri di più
Ecco alcune idee che puoi mettere in pratica per approfondire:
- Aggiungi modalità e attiva/disattiva al dispositivo.
- Aggiungi altri trait supportati al tuo dispositivo.
- Scopri l'esecuzione locale per la smart home.
- Dai un'occhiata all'esempio di GitHub per saperne di più.
Puoi anche scoprire di più su come testare e inviare un'azione per la revisione, inclusa la procedura di certificazione per pubblicare l'azione per gli utenti.