Guida ai sistemi 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, ad esempio un sensore che rileva movimenti o una finestra aperta.
Questo tipo indica che al dispositivo viene visualizzata l'icona Sistema di sicurezza e alcuni sinonimi e alias correlati.
Funzionalità del dispositivo
Fai riferimento alla documentazione relativa ai trait corrispondente 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 di functionNotSupported in una risposta QUERY o EXECUTE. Per ulteriori informazioni, consulta Errori ed eccezioni.
Trait consigliati
Questi trait sono consigliati, se applicabili al tuo dispositivo. Tuttavia, puoi combinare tutte le caratteristiche disponibili per associarle al meglio alle funzionalità esistenti del prodotto.
Requisiti di qualità
- Latenza: deve essere inferiore o uguale a 2000 ms.
- Affidabilità: deve essere superiore o uguale al 97%.
Dispositivo di esempio: sistema di sicurezza semplice
Questa sezione contiene esempi di payload per intent che rappresentano un "sistema di sicurezza" comune in base al tipo di dispositivo e ai trait indicati sopra. Se aggiungi o rimuovi i trait nell'implementazione, modifica le risposte di conseguenza per riflettere questi cambiamenti.
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"
}
]
}
}
}
}
Esempi di comandi EXECUTE
ArmDisarm
Per ulteriori dettagli sui parametri del comando, consulta il riferimento
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 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 che segnali tramite il trait StatusReport. Le eccezioni possono essere segnalate come blocchi o non bloccanti.
- Le eccezioni non di blocco segnalate con lo stato "SUCCESS" indicano che l'eccezione non ha impedito l'abilitazione o il disabilitazione.
- Le eccezioni di blocco segnalate con lo stato "EXCEPTIONS" indicano che l'abilitazione o la disabilitazione è stata arrestata a causa di queste eccezioni.
I codici di eccezione comunemente associati ai sistemi di sicurezza includono:
doorOpen: c'è una porta aperta.windowOpen: c'è una finestra aperta.isOpen: un sensore rileva che qualcosa è aperto, ma non sa se si tratta di una porta o di una finestra.
Esempio: eccezione non bloccante
Questo esempio mostra un'eccezione non di blocco in cui il sistema di sicurezza è abilitato anche se una finestra viene segnalata come aperta.
| User | Imposta il sistema di sicurezza su sicurezza elevata. |
| 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 sicurezza elevata. |
| Assistente Google | Si è verificato un errore durante il controllo del sistema di sicurezza. La finestra anteriore è aperta. |
{
"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": "EXCEPTIONS",
"states": {
"online": true,
"isArmed": false,
"currentArmLevel": "L2",
"currentStatusReport": [
{
"blocking": true,
"priority": 0,
"statusCode": "windowOpen",
"deviceTarget": "sensor_id1"
}
]
}
}
]
}
}
Abilitazione con autenticazione a due fattori
Se il flusso di abilitazione richiede agli utenti di inserire un PIN tramite una finestra di dialogo autenticazione a due fattori, devi confermare se vogliono continuare ad abilitare il sistema in caso di eccezioni attive (ad esempio, quando è aperta una finestra o una porta).
Questo scenario potrebbe richiedere sia un PIN sia una passphrase, seguito da una conferma.
Esempio: sfida di riconoscimento
Questo esempio mostra un utente che tenta di abilitare il sistema di sicurezza, ma una porta principale viene rilevata come aperta. L'utente riconosce 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. 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 parte di Google conterrà il risultato di 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 tramite PIN e accettazione
Questo esempio mostra un utente che tenta di abilitare il sistema di sicurezza che richiede l'inserimento del PIN. Il sistema rileva che i finestrini anteriore e posteriore sono aperti e chiede all'utente di confermare che l'abilitazione deve procedere.
| User | Braccio a distanza. |
| Assistente Google | Qual è il PIN? |
| User | 1234. |
| Assistente Google | Sembra che il finestrino anteriore e posteriore siano aperti. Vuoi continuare ad abilitare il sistema di sicurezza? |
| User | Sì. |
| Assistente Google | Ok, attivo il sistema di sicurezza per 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 risponde quindi a una richiesta contenente il PIN fornito. Per supportare il secondo turno, devi rispondere con una sfida 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 conterrà solo il risultato di 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
}
}
]
}
}