Come integrare nei tuoi dispositivi
Google Home
Quest'opera è distribuita con Licenza Creative Commons Attribuzione - Condividi allo stesso modo 4.0 Internazionale.
Agenda
Ovvero, cose serve fare per accendere la lampadina
💡
Ma prima.... Cos'è Google Home???
Google Home è una piattaforma di automazione domestica che consente il controllo e la gestione di vari dispositivi intelligenti all'interno della casa utilizzando comandi vocali o l'app Google Home.
Funziona in combinazione con l'Assistente Google, un assistente virtuale basato sull'intelligenza artificiale che risponde ai comandi vocali degli utenti.
Supporta una vasta gamma di dispositivi intelligenti, tra cui luci, termostati, telecamere di sicurezza, altoparlanti intelligenti....
...e chi sei tu???
informatico (ed un po anche elettronico) per passione
Attualmente lavoro presso Kalpa, un'azienda specializzata in soluzioni IoT e automazione industriale, ma non solo.
Negli ultimi 10 anni mi sono occupato di progettazione e sviluppo di sistemi IoT (principalmente domotica).
In passato ho lavorato in ambito Web (Corriere della Sera), Telco (Italtel), GDO (Carrefour).
La tua piattaforma IoT
Ovviamente serve avere già una piattaforma IoT e dei dispositivi "connessi".
Serve poter fare autenticazione con OAuth 2.0. Google Home, infatti, attraverso l'uso dell'Identity Provider, otterrà un token di accesso relativo all'utente per inviare i comandi.
La tua piattaforma IoT
La tua piattaforma IoT (senza pretese...)
La tua piattaforma IoT con Integrazione
La tua piattaforma IoT con Integrazione (senza pretese...)
Autenticazione
Il flusso di autenticazione con Google Home (Account linking):
- L'utente seleziona il servizio "Funziona con Google" nell'app Google Home.
- Google Home reindirizza l'utente al server di autenticazione della tua piattaforma per il login.
- L'utente effettua il login e concede le autorizzazioni necessarie.
- Il server di autenticazione reindirizza l'utente di nuovo a Google Home con un codice.
- Google Home scambia il codice con un access e refresh token attraverso una chiamata al server di autenticazione.
- Google Home utilizza l'access token per effettuare richieste API al tuo backend.
Il flusso di autenticazione con Google Home (Account linking):
Il flusso di autenticazione con Google Home:
Il flusso di autenticazione con Google Home:
Nella demo useremo Keycloak (ma è possibile anche usare Google Identity Platform, ma solo con la registrazione del dominio)
Oppure potete creare il vostro server IdP sequendo queste istruzioni (non consigliato...).
Configurazione di Keycloak
Nelle immagini che seguono vediamo come configurare Keycloak per l'integrazione con Google Home.
Ma, indipendentemente dal server IdP che usate, serve ottenere questi 5 parametri:
- Authorization Endpoint URL
- Token Endpoint URL
- Client ID
- Client Secret
- Scopes
Creazione progetto e configurazione Account Linking
Progetto Google Home e Google Cloud sono la stessa cosa
1. Creare un progetto su Google Home Console
2. Configurare le credenziali OAuth 2.0 (URL OAuth2, Client ID, Client Secret, Scopes)
3. Creare credenziali di servizio per chiamare verso Home Graph
Creazione e configurazione progetto su Google Home
Creazione e configurazione progetto su Google Home
Creazione e configurazione progetto su Google Home
Creazione e configurazione progetto su Google Home
Creazione e configurazione progetto su Google Home
Creazione e configurazione progetto su Google Home
Creazione e configurazione progetto su Google Home
Creazione e configurazione progetto su Google Home
Per poter informare Google Home circa il cambio di stato dei nostri dispositivi, è necessario utilizzare le credenziali di servizio per richiamare HomeGraph API.
Abilitata l'API è possibile creare il service account e scaricare il file con le credenziali
Abilitata l'API è possibile creare il service account e scaricare il file con le credenziali
Abilitata l'API è possibile creare il service account e scaricare il file con le credenziali
Abilitata l'API è possibile creare il service account e scaricare il file con le credenziali
Abilitata l'API è possibile creare il service account e scaricare il file con le credenziali
Abilitata l'API è possibile creare il service account e scaricare il file con le credenziali
Abbiato tutto l'occorrente per implementare il nostro backend
Già adesso possiamo vedere il nostro progetto su "Funziona con google"
Attenzione l'account utilizzato sullo smartphone deve essere lo stesso utilizzato per la configurazione del progetto Google Home
Funzionamento di Google Home
Google Home mantiene l'elenco dei dispositivi, le loro caratteristiche ed il loro stato.
Esegue chiamate ReST verso l'endpoint della piattaforma per scoprire quali sono i dispositivi dell'utente ed il loro stato.
Mentre la nostra piattaforma fa chiamate ReST verso Google Home (HomeGraph) per aggiornare i dati in cloud sul cambio dello stato dei dispositivi o aggiunta/rimozioni dei dispositivi stessi.
Funzionamento di Google Home
| Da Google | Verso Google |
|---|---|
| SYNC QUERY EXECUTE DISCONNECT |
RequestSync ReportStateAndNotifications query sync delete |
1. Richiesta di SYNC
1. Richiesta di SYNC: Esempio di richiesta
{
"requestId": "9317802151529365959"
"inputs": [
{
"intent": "action.devices.SYNC"
}
],
}
1. Richiesta di SYNC: Esempio di risposta
{
"requestId": "13274642849947722297",
"payload": {
"agentUserId": "82f453bd-86f4-45f3-a0fa-0daf4af3e655",
"devices": [{
"id": "82f453l3d",
"type": "action.devices.types.SENSOR",
"traits": [
"action.devices.traits.SensorState"
],
"attributes": {
"sensorStatesSupported": [
{
"name": "CarbonMonoxideLevel",
"availableStates": [
"high",
"carbon monoxide detected",
"no carbon monoxide detected",
"unknown"
],
"numericCapabilities": {
"rawValueUnit": "PARTS_PER_MILLION"
}
}
]
},
"name": {
"defaultNames": [],
"name": "Sensori",
"nicknames": []
},
"willReportState": true,
"notificationSupportedByAgent": true,
"customData": {}
},{
"id": "82f453l3",
"type": "action.devices.types.LIGHT",
"traits": [
"action.devices.traits.Brightness",
"action.devices.traits.Modes",
"action.devices.traits.OnOff",
"action.devices.traits.ColorSetting"
],
"attributes": {
"commandOnlyBrightness": false,
"commandOnlyModes": false,
"queryOnlyModes": false,
"availableModes": [
{
"name": "mode",
"ordered": false,
"name_values": [
{
"lang": "it",
"name_synonym": [
"Modalità"
]
},
{
"lang": "en",
"name_synonym": [
"Mode"
]
}
],
"settings": [
{
"setting_name": "fix",
"setting_values": [
{
"lang": "it",
"setting_synonym": [
"Fisso"
]
},
{
"lang": "en",
"setting_synonym": [
"Fix",
"Fixed"
]
}
]
},
{
"setting_name": "snake",
"setting_values": [
{
"lang": "it",
"setting_synonym": [
"Serpente"
]
},
{
"lang": "en",
"setting_synonym": [
"Snake"
]
}
]
},
{
"setting_name": "arlecchino",
"setting_values": [
{
"lang": "it",
"setting_synonym": [
"Arlecchino"
]
},
{
"lang": "en",
"setting_synonym": [
"Arlecchino"
]
}
]
},
{
"setting_name": "rainbow",
"setting_values": [
{
"lang": "it",
"setting_synonym": [
"Arcobaleno"
]
},
{
"lang": "en",
"setting_synonym": [
"Rainbow"
]
}
]
}
]
}
],
"commandOnlyOnOff": false,
"queryOnlyOnOff": false,
"commandOnlyColorSetting": false,
"colorModel": "rgb",
"colorTemperatureRange": {
"temperatureMinK": 3000,
"temperatureMaxK": 9000
}
},
"name": {
"defaultNames": [],
"name": "Lampada",
"nicknames": []
},
"willReportState": true,
"customData": {}
},
{
"id": "82f453l3b",
"type": "action.devices.types.GARAGE",
"traits": [
"action.devices.traits.OpenClose"
],
"attributes": {
"discreteOnlyOpenClose": true,
"commandOnlyOpenClose": false,
"queryOnlyOpenClose": false,
"openDirection": []
},
"name": {
"defaultNames": [],
"name": "Garage",
"nicknames": []
},
"willReportState": true,
"customData": {}
}
]
}
}
Come viene descritto un dispositivo:
- id: identificativo univoco del dispositivo (univoco per tutti i dispositivi della tua integrazione)
- type: tipo di dispositivo (es. action.devices.types.LIGHT)
- traits: elenco delle caratteristiche supportate dal dispositivo (es. OnOff, Brightness, ColorSetting)
- attributes: attributi specifici per ogni trait supportato
- name: nome del dispositivo
- willReportState: indica se il dispositivo può segnalare autonomamente i cambiamenti di stato
- customData: dati personalizzati associati al dispositivo
- notificationSupportedByAgent: indica se il dispositivo supporta le notifiche
- roomHint: suggerimento sulla stanza in cui si trova il dispositivo
- ...
Tool Validazione SYNC Response
Google fornisce un tool per validare la risposta alla SYNC, disponibile all'indirizzo https://developers.home.google.com/cloud-to-cloud/tools/sync-data-validator.
Lo scambio delle informazioni per sincronizzare lo stato dei dispositivi
Con la SYNC viene sincronizzato l'elenco dei dispositivi e le loro caratteristiche, per mandetere aggiornato lo stato vengono utilizzate due chiamate HTTP:
- QUERY da Google Home
- ReportStateAndNotifications verso Google Graph
1. Richiesta di QUERY
2. Richiesta di QUERY: Esempio di richiesta
{
"requestId": "22666971838881680",
"inputs": [
{
"intent": "action.devices.QUERY",
"payload": {
"devices": [
{
"customData": {},
"id": "82f453l3d"
},
{
"customData": {},
"id": "82f453l3"
},
{
"customData": {},
"id": "82f453l3b"
}
]
}
}
]
}
2. Richiesta di QUERY: Esempio di risposta
{
"requestId": "22666971838881680",
"payload": {
"devices": {
"82f453l3": {
"online": true,
"status": "SUCCESS",
"currentModeSettings": {"mode":"rainbow"},
"color": { "spectrumRgb": 65280 },
"on": false,
"brightness": 10
},
"82f453l3d": {
"online": true,
"status": "SUCCESS",
"currentSensorStateData": [
{
"alarmState": "IDLE",
"alarmSilenceState": "ALLOWED",
"rawValue": 0,
"name": "CarbonMonoxideLevel",
"currentSensorState": "no carbon monoxide detected"
}
]
},
"82f453l3b": {
"online": true,
"status": "SUCCESS",
"openPercent": 0
}
}
}
}
2. Risposta a QUERY
Stato del dispositivo:
- online: indica se il dispositivo è attualmente online
- status: stato della richiesta per il dispositivo (SUCCESS, OFFLINE, EXCEPTIONS, ERROR)
Stato del dispositivo (relativi ad i trait implementati):
- on: booleano che indica se il dispositivo è acceso (true) o spento (false).
- color: oggetto che rappresenta lo stato del colore del dispositivo, con proprietà come spectrumRgb (valore RGB del colore) o temperatureK (temperatura del colore in Kelvin).
- brightness: intero che rappresenta il livello di luminosità del dispositivo, solitamente compreso tra 0 e 100.
- ....
Richiesta di reportStateAndNotification
Richiesta di reportStateAndNotification: Esempio di richiesta con aggiornamento di Stato
{
"agentUserId": "82f453bd-86f4-45f3-a0fa-0daf4af3e655",
"requestId": "93348d98-3ca5-4eb5-b61b-4f76b8796e0c",
"payload": {
"devices": {
"states": {
"82f453l3": {
"currentModeSettings": {"mode": "rainbow"},
"online": true
}
}
}
}
}
3. Richiesta di EXECUTE
3. Richiesta di EXECUTE: Esempio di richiesta
{
"requestId": "10035348206248233836",
"inputs": [ {
"context": {
"locale_country": "US",
"locale_language": "en"
},
"intent": "action.devices.EXECUTE",
"payload": {
"commands": [ {
"devices": [ {
"customData": {},
"id": "82f453l3"
} ],
"execution": [ {
"command": "action.devices.commands.OnOff",
"params": { "on": true }
}]
}
]
}
}
]
}
3. Richiesta di EXECUTE: Esempio di risposta
{
"requestId": "10035348206248233836",
"payload": {
"commands": [ {
"ids": [ "82f453l3"],
"status": "SUCCESS",
"states": {
"online": true,
"on": false
}
} ]
}
}
3. Richiesta di EXECUTE: Esempio di risposta con EXCEPTIONS
{
"requestId": "18414852243113253962",
"payload": {
"commands": [ {
"ids": [ "82f453l3" ],
"status": "SUCCESS",
"states": {
"online": true,
"exceptionCode": "lowBattery",
"status": "EXCEPTIONS",
"brightness": 50,
"on": true
}
}
]
}
}
Richiesta di reportStateAndNotification: Proactive notifications
Per alcuni trait è possibile inviare una notifica a Google Home che che viene inoltrata ai dispositivi Google (solo da dispositivi Smart Speaker e Smart Display no sullo smartphone):
Richiesta di reportStateAndNotification: Esempio di richiesta con Proactive notifications
{
"agentUserId": "82f453bd-86f4-45f3-a0fa-0daf4af3e655",
"requestId": "6a80313d-738b-47ae-b856-b49dc3e410bd",
"eventId": "88d629eb-60d8-41c9-9699-53b1fd25c846",
"payload": {
"devices": {
"notifications": {
"82f453l3d": {
"SensorState": {
"name": "CarbonMonoxideLevel",
"currentSensorState": "high",
"priority": 0
}
}
},
"states": {
"82f453l3d": {
"online": true,
"currentSensorStateData": [ {
"alarmState": "ALARM",
"alarmSilenceState": "ALLOWED",
"rawValue": 1234.0,
"name": "CarbonMonoxideLevel",
"currentSensorState": "high" } ]
}
}
}
}
}
Richiesta di reportStateAndNotification: follow-up responses
Per alcuni trait è possibile inviare avanzamenti di stato a Google Home nel momento in cui si eseguono dei comandi:
Funzionamento di Google Home
4. Richiesta di DISCONNECT
Errori globali ( Quando tutti i dispositivi hanno lo stesso errore)
Tipicamente i dispositivi in casa sono collegati ad un gateway, se questo gateway risulta offline oppure è in aggiornamento è possibile rispondere con un errore globale:
{
"requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"payload": {
"errorCode": "deviceOffline",
"status" : "ERROR"
}
}
Come invitare utenti a provare il tuo dispositivo su Google Home.
Dall'account dell'inviato andare su Console Google Home, aprire il processo e proseguire accettando il test
Da ricordare...
La documentazione non è sempre esatta e completa.
Provare, provare, provare, provare, provare,
Debug e strumenti di sviluppo
Home Graph Viewer
Home Graph Viewer è uno strumento fornito da Google per gli sviluppatori che consente di visualizzare e analizzare lo stato dei dispositivi collegati a Google Home attraverso l'API Home Graph. Questo strumento è particolarmente utile per il debug e la risoluzione dei problemi durante lo sviluppo di integrazioni con Google Home.
Smart Home SYNC Data Validator
Il Smart Home SYNC Data Validator è uno strumento fornito da Google per gli sviluppatori che consente di convalidare i dati di sincronizzazione (SYNC) inviati al cloud di Google Home. Questo strumento aiuta gli sviluppatori a garantire che i dati dei dispositivi siano formattati correttamente e conformi alle specifiche richieste da Google Home.
Utilizzando il SYNC Data Validator, gli sviluppatori possono identificare e correggere eventuali errori nei dati di sincronizzazione prima di inviarli al cloud, migliorando così l'affidabilità e la compatibilità delle loro integrazioni con Google Home.
Google Home Playground
Google Home Playground è uno strumento interattivo fornito da Google per gli sviluppatori che consente di testare e sperimentare le funzionalità di Google Home e dell'Assistente Google in un ambiente simulato. Questo strumento è particolarmente utile per il debug e la risoluzione dei problemi durante lo sviluppo di integrazioni con Google Home.
Utilizzando Google Home Playground, gli sviluppatori possono simulare comandi vocali, interazioni con dispositivi intelligenti e scenari di utilizzo comuni per verificare il corretto funzionamento delle loro applicazioni e servizi prima di rilasciarli agli utenti finali.
Google Home Extension for VS Code
La Google Home Extension for VS Code è un'estensione per l'editor di codice Visual Studio Code che fornisce agli sviluppatori strumenti e funzionalità specifiche per lo sviluppo di integrazioni con Google Home e l'Assistente Google. Questa estensione semplifica il processo di sviluppo, test e debug delle applicazioni e dei servizi destinati alla piattaforma Google Home.
Utilizzando la Google Home Extension for VS Code, gli sviluppatori possono accedere rapidamente alla documentazione, eseguire test automatizzati e gestire le configurazioni del progetto direttamente all'interno dell'editor, migliorando così l'efficienza e la produttività durante lo sviluppo.
Google Home Test Suite (GHTS)
La Google Home Test Suite (GHTS) è un insieme di strumenti e risorse forniti da Google per aiutare gli sviluppatori a testare e convalidare le loro integrazioni con Google Home e l'Assistente Google. La GHTS consente agli sviluppatori di eseguire test automatizzati e manuali per garantire che le loro applicazioni funzionino correttamente con la piattaforma Google Home.
La GHTS include una serie di test predefiniti che coprono vari aspetti dell'integrazione, come la gestione dei comandi vocali, la risposta dell'Assistente Google e l'interazione con i dispositivi intelligenti. Gli sviluppatori possono utilizzare questi test per identificare e risolvere eventuali problemi prima di rilasciare le loro applicazioni agli utenti finali.
Certificazione WWGH (Work With Google Home)
La certificazione WWGH (Work With Google Home) è un programma di certificazione offerto da Google per gli sviluppatori e i produttori di dispositivi intelligenti che desiderano garantire la compatibilità e l'integrazione con la piattaforma Google Home. Ottenere la certificazione WWGH dimostra che un dispositivo o un'applicazione soddisfa gli standard di qualità e prestazioni stabiliti da Google per garantire un'esperienza utente ottimale.
Per ottenere la certificazione WWGH, gli sviluppatori devono sottoporre i loro dispositivi o applicazioni a una serie di test e valutazioni condotti da Google. Questi test coprono vari aspetti dell'integrazione, come la gestione dei comandi vocali, la risposta dell'Assistente Google e l'interazione con i dispositivi intelligenti.
Altri aspetti: App Flip
L'App Flip è una funzionalità che consente agli utenti di fare l'account linking in maniera semplice e veloce, richiamando l'applicazione del vendor piuttosto che aprire una web view e chiedere l'autenticazione all'utente.
Altri aspetti: Secondary User Verification
La verifica secondaria dell'utente è una funzionalità che consente a Google Home di riconoscere e autenticare più utenti all'interno della stessa abitazione. Questo è particolarmente utile in contesti familiari, dove diversi membri possono avere esigenze e preferenze diverse.
Questa funzionalità si basa sull'uso di tecnologie di riconoscimento vocale e di machine learning per identificare gli utenti in base alla loro voce e alle loro interazioni con il dispositivo. Le informazioni vocali vengono elaborate localmente e nel cloud per migliorare l'accuratezza del riconoscimento e garantire un'esperienza personalizzata per ogni utente.
Questa funzionalità è particolarmente utile in contesti familiari, dove diversi membri possono avere esigenze e preferenze diverse.
Altri aspetti: Deep Link
I Deep Link sono URL speciali che consentono agli utenti di accedere direttamente a specifiche funzionalità o contenuti all'interno di un'applicazione mobile o di un sito web. Nel contesto di Google Home, i Deep Link possono essere utilizzati per collegare rapidamente gli utenti a determinate azioni o impostazioni all'interno dell'app Google Home o di altre app compatibili.
Questa funzionalità migliora l'esperienza utente, consentendo agli utenti di accedere rapidamente alle funzionalità desiderate senza dover navigare manualmente attraverso l'app o il sito web.
Altri aspetti: Local fulfillment
Il Local Home SDK è un kit di sviluppo software fornito da Google che consente agli sviluppatori di creare applicazioni e servizi che possono interagire con i dispositivi intelligenti all'interno della rete locale dell'utente. Questo SDK consente agli sviluppatori di sfruttare le funzionalità dei dispositivi intelligenti senza dover fare affidamento esclusivamente sulla connessione cloud.
Utilizzando il Local Home SDK, gli sviluppatori possono creare esperienze più reattive e affidabili per gli utenti di Google Home, migliorando la velocità di risposta e riducendo la dipendenza dalla connettività Internet.
Questa funzionalità è particolarmente utile in contesti in cui la latenza della rete può influire negativamente sull'esperienza utente, come nel caso di comandi vocali o automazioni domestiche che richiedono una risposta immediata.
DEMO
Analisi del backend di esempio disponibile qui.
Risorse utili
Documentazione ufficiale Google Home: qui
Esempio di backend di integrazione: qui
Grazie per l'attenzione!
Queste slide sono disponibili qui: