Guida ai sistemi di sicurezza per la smart home
action.devices.types.SECURITYSYSTEM: i sistemi di sicurezza possono essere attivati e disattivati. Possono essere attivati a più livelli di sicurezza (ad esempio, A casa e Fuori) e possono segnalare informazioni su determinati sensori, come un sensore che rileva movimento o una finestra aperta.
Questo tipo indica che il dispositivo riceve l'icona Sistema di sicurezza e alcuni sinonimi e alias correlati.
Funzionalità dispositivo
Fai riferimento alla documentazione delle caratteristiche corrispondente per ulteriori dettagli sull'implementazione, ad esempio attributi e stati che il servizio deve supportare e come creare risposte EXECUTE e QUERY.
Caratteristiche obbligatorie
Questi tratti e comandi sono obbligatori, se pertinenti al tuo dispositivo.
Tratti consigliati
Queste caratteristiche sono consigliate, se applicabili al tuo dispositivo. Tuttavia, puoi modificare e abbinare tutte le caratteristiche disponibili per trovare una corrispondenza ottimale con le tue funzionalità di prodotto esistenti.
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 degli intent che rappresentano un "sistema di sicurezza" comune in base al tipo di dispositivo e alle caratteristiche citate sopra. Se aggiungi o rimuovi caratteristiche nell'implementazione, modifica le risposte di conseguenza per riflettere tali 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"
}
]
}
}
}
}
Esempi di comandi EXECUTE
ArmDisarm
Per ulteriori dettagli sui parametri dei comandi, 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 del dispositivo
Consulta l'elenco completo degli errori e delle eccezioni.Segnala le eccezioni di attivazione
Quando tenti di abilitare o disabilitare il sistema, puoi fornire un contesto aggiuntivo tramite i codici di eccezione che segnali tramite la caratteristica StatusReport. Le eccezioni possono essere segnalate come con blocco o senza blocco.
- Le eccezioni non bloccanti segnalate con lo stato "SUCCESS" indicano che l'eccezione non ha impedito l'abilitazione o la disabilitazione.
- Le eccezioni di blocco con stato "ECCEZIONI" indicano che l'abilitazione o la disabilitazione sono state interrotte a causa di queste eccezioni.
I codici di eccezione comunemente associati ai sistemi di sicurezza includono:
doorOpen: è stata aperta una porta.windowOpen: viene aperta una finestra.isOpen: un sensore rileva che qualcosa è aperto, ma non sa se è una porta o una finestra.
Esempio: eccezione non bloccante
Questo esempio mostra un'eccezione non bloccante in cui il sistema di sicurezza viene abilitato anche se una finestra viene segnalata come aperta.
| Utente | Imposta il sistema di sicurezza su Alta sicurezza. |
| l'Assistente Google | Ok, la finestra anteriore è aperta. Abilitare il sistema di sicurezza ad 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
| Utente | Imposta il sistema di sicurezza su Alta sicurezza. |
| l'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": "SUCCESS",
"states": {
"online": true,
"isArmed": false,
"currentArmLevel": "L2",
"currentStatusReport": [
{
"blocking": true,
"priority": 0,
"statusCode": "windowOpen",
"deviceTarget": "sensor_id1"
}
]
}
}
]
}
}
Abilitare l'autenticazione a due fattori
Se il flusso di inserimento 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 in caso di eccezioni attive (ad esempio, quando è aperta una finestra o una porta).
Questo scenario potrebbe richiedere sia un PIN sia la voce di passphrase, seguita da una conferma.
Esempio: verifica di riconoscimento
Questo esempio mostra un utente che cerca di abilitare il sistema di sicurezza, ma viene rilevata come aperta una porta d'ingresso. L'utente riconosce che il sistema di sicurezza deve essere abilitato anche se la porta d'ingresso è aperta.
| Utente | Abilita il sistema di sicurezza. |
| l'Assistente Google | La porta d'ingresso è aperta. Vuoi abilitare il sistema di sicurezza? |
| Utente | Sì, |
| l'Assistente Google | Ok, abilitare 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 che riceverai da 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 conferma
L'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 procedere.
| Utente | Braccio via. |
| l'Assistente Google | Qual è il tuo PIN? |
| Utente | 1234. |
| l'Assistente Google | Sembra che la finestra anteriore e quella posteriore siano aperte. Vuoi continuare ad abilitare il sistema di sicurezza? |
| Utente | Sì, |
| l'Assistente Google | Ok, abilitare il sistema di sicurezza |
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 ti invia poi una richiesta contenente il PIN fornito. Per supportare la seconda svolta, devi rispondere con una verifica ackNeeded fornendo informazioni aggiuntive, incluso il livello del gruppo target e il report di 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 richiesta successiva inviata da Google conterrà solo il risultato ack e non il PIN fornito alla prima svolta.
{
"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
}
}
]
}
}