Guida al sistema di sicurezza per la smart home
action.devices.types.SECURITYSYSTEM
- I sistemi di sicurezza possono essere abilitati e disabilitati. Possono essere abilitati a più livelli di sicurezza (ad esempio, a casa e fuori) e possono segnalare informazioni su determinati sensori, come un sensore che rileva movimenti o una finestra aperta.
Questo tipo indica che sul dispositivo viene mostrata l'icona del sistema di sicurezza e alcuni sinonimi e alias correlati.
Funzionalità del dispositivo
Fai riferimento alla documentazione relativa ai tratti corrispondenti per i dettagli sull'implementazione, ad esempio gli attributi e gli stati che il tuo servizio dovrebbe supportare, e come creare risposte EXECUTE e QUERY.
Trait obbligatori
Questi trait e comandi sono obbligatori, se applicabili al tuo
dispositivo. Se il tuo dispositivo non supporta questi trait, inserisci il codice di errore functionNotSupported
in una risposta QUERY o EXECUTE. Per ulteriori informazioni, consulta Errori ed eccezioni.
Trait consigliati
Queste caratteristiche sono consigliate, se applicabili al tuo dispositivo. Tuttavia, puoi combinare e abbinare tutti i tratti disponibili per abbinare al meglio le funzionalità del prodotto esistente.
Requisiti di qualità
- Latenza: deve essere inferiore o uguale a 2000 ms.
- Affidabilità:deve essere superiore o uguale al 97%.
Esempio di dispositivo: sistema di sicurezza semplice
Questa sezione contiene payload di intent di esempio che rappresentano un "Sistema di sicurezza" comune in base al tipo di dispositivo e ai trait riportati sopra. Se aggiungi o rimuovi trait nell'implementazione, modifica le risposte di conseguenza per riflettere queste modifiche.
Esempio di risposta SYNC
{ "requestId": "6894439706274654512", "inputs": [ { "intent": "action.devices.SYNC" } ] }
{ "requestId": "6894439706274654512", "payload": { "agentUserId": "user123", "devices": [ { "id": "123", "type": "action.devices.types.SECURITYSYSTEM", "traits": [ "action.devices.traits.StatusReport", "action.devices.traits.ArmDisarm" ], "name": { "name": "Simple security system" }, "willReportState": true, "attributes": { "availableArmLevels": { "levels": [ { "level_name": "home_key", "level_values": [ { "level_synonym": [ "Home and Guarding", "level 1", "home", "SL1" ], "lang": "en" } ] }, { "level_name": "away_key", "level_values": [ { "level_synonym": [ "Away and Guarding", "level 2", "away", "SL2" ], "lang": "en" } ] } ], "ordered": true } }, "deviceInfo": { "manufacturer": "smart-home-inc", "model": "hs1234", "hwVersion": "3.2", "swVersion": "11.4" } } ] } }
Esempio di risposta QUERY
{ "requestId": "6894439706274654514", "inputs": [ { "intent": "action.devices.QUERY", "payload": { "devices": [ { "id": "123" } ] } } ] }
{ "requestId": "6894439706274654514", "payload": { "devices": { "123": { "status": "SUCCESS", "online": true, "isArmed": true, "currentArmLevel": "home_key", "currentStatusReport": [ { "blocking": false, "deviceTarget": "123", "priority": 0, "statusCode": "lowBattery" } ] } } } }
Comandi EXECUTE di esempio
ArmDisarm
Per ulteriori dettagli sui parametri di comando, consulta la documentazione di riferimento su
action.devices.traits.ArmDisarm
.
{ "requestId": "6894439706274654516", "inputs": [ { "intent": "action.devices.EXECUTE", "payload": { "commands": [ { "devices": [ { "id": "123" } ], "execution": [ { "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "away_key" } } ] } ] } } ] }
{ "requestId": "6894439706274654516", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "online": true, "isArmed": true, "currentArmLevel": "away_key" } } ] } }
ERRORI del dispositivo
Consulta l'elenco completo di errori ed eccezioni.Segnala eccezioni di attivazione
Quando provi ad abilitare o disabilitare il sistema, puoi fornire ulteriore contesto tramite i codici di eccezione segnalati tramite il trait StatusReport. Le eccezioni possono essere segnalate come di blocco o di non blocco.
- Le eccezioni non di blocco segnalate con lo stato "SUCCESS" indicano che l'eccezione non ha impedito l'abilitazione o la disabilitazione.
- Le eccezioni di blocco segnalate con lo stato "ECCEZIONI" indicano che l'abilitazione o la disabilitazione è stata interrotta a causa di queste eccezioni.
I codici di eccezione comunemente associati ai sistemi di sicurezza includono:
doorOpen
: c'è una porta aperta.windowOpen
: è aperta una finestra.isOpen
: un sensore rileva qualcosa che è aperto, ma non sa se si tratta di una porta o di una finestra.
Esempio: eccezione che non blocca
Questo esempio mostra un'eccezione non bloccante in cui il sistema di sicurezza è abilitato anche se una finestra viene segnalata come aperta.
User | Imposta il sistema di sicurezza su Protezione alta. |
Assistente Google | Ok, il finestrino anteriore è aperto. Abilito il sistema di sicurezza su alta sicurezza. |
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123" }], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "L2" } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "online": true, "isArmed": true, "currentArmLevel": "L2", "currentStatusReport": [ { "blocking": false, "priority": 0, "statusCode": "windowOpen", "deviceTarget": "sensor_id1" } ] } } ] } }
Esempio: eccezione di blocco
User | Imposta il sistema di sicurezza su Protezione alta. |
Assistente Google | Si è verificato un errore durante il controllo del sistema di sicurezza. Il finestrino anteriore è aperto. |
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123" }], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "L2" } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "online": true, "isArmed": false, "currentArmLevel": "L2", "currentStatusReport": [ { "blocking": true, "priority": 0, "statusCode": "windowOpen", "deviceTarget": "sensor_id1" } ] } } ] } }
Abilitazione dell'autenticazione a due fattori
Se il flusso di attivazione richiede agli utenti di inserire un PIN tramite una finestra di dialogo per l'autenticazione a due fattori, devi confermare se vogliono continuare ad abilitare il sistema quando ci sono eccezioni attive, ad esempio quando è aperta una finestra o una porta.
Questo scenario potrebbe richiedere sia l'inserimento di un PIN che di una passphrase, seguiti da una conferma.
Esempio: sfida di riconoscimento
Questo esempio mostra un utente che tenta di abilitare il sistema di sicurezza, ma una porta d'ingresso viene rilevata come aperta. L'utente conferma che il sistema di sicurezza deve essere abilitato anche se la porta principale è aperta.
User | Abilita il sistema di sicurezza. |
Assistente Google | La porta d'ingresso è aperta. Vuoi abilitare il sistema di sicurezza? |
User | Sì. |
Assistente Google | Ok, abilito il sistema di sicurezza. |
Nel primo turno, devi rispondere con una sfida ackNeeded
.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123" }], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "ERROR", "errorCode": "challengeNeeded", "challengeNeeded": { "type": "ackNeeded" }, "states": { "isArmed": true, "currentArmLevel": "L2", "currentStatusReport": [ { "blocking": false, "priority": 0, "statusCode": "doorOpen", "deviceTarget": "456" } ] } } ] } }
La successiva richiesta da Google a te conterrà il risultato ack
.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123" }], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true }, "challenge": { "ack": true } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "isArmed": true } } ] } }
Esempio: verifica del PIN e della conferma
Questo esempio mostra un utente che tenta di abilitare il sistema di sicurezza che richiede l'inserimento del PIN. Il sistema rileva che le finestre anteriore e posteriore sono aperte e chiede all'utente di confermare che l'abilitazione deve continuare.
User | Abilita per Fuori. |
Assistente Google | Qual è il tuo PIN? |
User | 1234. |
Assistente Google | Sembra che il finestrino anteriore e il finestrino posteriore siano aperti. Vuoi continuare ad abilitare il sistema di sicurezza in modalità Fuori? |
User | Sì. |
Assistente Google | Ok, abilito il sistema di sicurezza su Fuori |
Nel primo turno, devi rispondere con una sfida pinNeeded
standard.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123" }], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["456"], "status": "ERROR", "errorCode": "challengeNeeded", "challengeNeeded": { "type": "pinNeeded" } }] } }
Google invia una seconda richiesta contenente il PIN fornito. Per supportare il secondo turno, devi rispondere con una richiesta di tipo ackNeeded
con informazioni aggiuntive, tra cui il livello del gruppo target e il report sullo stato attuale con eccezioni di blocco.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [...], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "away" }, "challenge": { "pin": "1234" } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["456"], "status": "ERROR", "states": { "targetArmLevel": "away", "currentStatusReport": [{ "blocking": true, "priority": 1, "deviceTarget": "front_window_id", "statusCode": "deviceOpen" }, { "blocking": true, "priority": 1, "deviceTarget": "back_window_id", "statusCode": "deviceOpen" } ] }, "errorCode": "challengeNeeded", "challengeNeeded": { "type": "ackNeeded" } }] } }
La successiva richiesta da parte di Google a te conterrà solo il risultato ack
,
e non il PIN fornito al primo turno.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [...], "execution": [{ "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "away" }, "challenge": { "ack": true } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "isArmed": true } } ] } }