Guía del sistema de seguridad para casas inteligentes
action.devices.types.SECURITYSYSTEM
: Los sistemas de seguridad se pueden activar y desactivar. Pueden activarse en varios niveles de seguridad (por ejemplo, En casa y Ausente) y pueden enviar información sobre ciertos sensores, como un sensor que detecta movimiento o una ventana abierta.
Este tipo indica que el dispositivo obtiene el ícono del sistema de seguridad y algunos sinónimos y alias relacionados.
Funciones del dispositivo
Consulta la documentación de las características correspondiente para obtener detalles de la implementación, como los atributos y los estados que tu servicio debe admitir, y cómo compilar respuestas EXECUTE y QUERY.
Características requeridas
Estas características y comandos son obligatorios, si corresponde a tu dispositivo. Si tu dispositivo no admite estas características, ingresa el código de error functionNotSupported
en una respuesta de QUERY o EXECUTE. Consulta Errores y excepciones para obtener más información.
Traits recomendados
Se recomiendan estas características (si corresponde) en tu dispositivo. Sin embargo, puedes combinar todas las características disponibles para que se adapten mejor a la funcionalidad del producto existente.
Requisitos de calidad
- Latencia: Debe ser menor o igual que 2,000 ms.
- Confiabilidad: Debe ser mayor o igual que el 97%.
Dispositivo de ejemplo: Sistema de seguridad simple
Esta sección contiene cargas útiles de intent de ejemplo que representan un "sistema de seguridad" común basado en el tipo de dispositivo y las características anteriores. Si agregas o quitas características en tu implementación, modifica tus respuestas según corresponda para reflejar esos cambios.
Respuesta de muestra de 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" } } ] } }
Ejemplo de respuesta de 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" } ] } } } }
Ejemplos de comandos EXECUTE
ArmDisarm
Para obtener detalles adicionales sobre los parámetros del comando, consulta la referencia de
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" } } ] } }
ERRORS de dispositivos
Consulta la lista completa de errores y excepciones.Informa excepciones de activación
Cuando intentes activar o desactivar el sistema, puedes proporcionar contexto adicional mediante los códigos de excepciones que informas a través de la característica StatusReport. Las excepciones se pueden informar como bloqueos o no bloqueos.
- Las excepciones sin bloqueo que se informaron con el estado "SUCCESS" indican que la excepción no impidió la activación o desactivación.
- Las excepciones de bloqueo que se informan con el estado "EXCEPTIONS" indican que se detuvo la activación o desactivación debido a estas excepciones.
A continuación, se indican los códigos de excepción que comúnmente se asocian con los sistemas de seguridad:
doorOpen
: Hay una puerta abierta.windowOpen
: Hay una ventana abierta.isOpen
: Un sensor detecta que algo está abierto (pero no sabe si es una puerta o una ventana).
Ejemplo: Excepción sin bloqueo
En este ejemplo, se muestra una excepción sin bloqueo en la que el sistema de seguridad está activado aunque se informe una ventana como abierta.
User | Establece el sistema de seguridad en el nivel alto. |
Asistente de Google | Muy bien, la ventana frontal está abierta. Se activará el sistema de seguridad con el nivel alto de seguridad. |
{ "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" } ] } } ] } }
Ejemplo: Excepción de bloqueo
User | Establece el sistema de seguridad en el nivel alto. |
Asistente de Google | Se produjo un error cuando se controlaba el sistema de seguridad. La ventana frontal está abierta. |
{ "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" } ] } } ] } }
Activación con autenticación de dos factores
Si tu flujo de activación requiere que los usuarios ingresen un PIN a través de un diálogo de autenticación de dos factores, debes confirmar si desean continuar activando el sistema cuando haya excepciones activas (por ejemplo, cuando una ventana o una puerta está abierta).
Esta situación puede requerir tanto una entrada de PIN o una frase de contraseña, seguida de una confirmación de recepción.
Ejemplo: Desafío de confirmación
En este ejemplo, se muestra un usuario que intenta activar el sistema de seguridad, pero se detecta que una puerta principal está abierta. El usuario reconoce que el sistema de seguridad debe activarse aunque la puerta principal esté abierta.
User | Activa el sistema de seguridad. |
Asistente de Google | La puerta principal está abierta. ¿Confirmas que quieres activar el sistema de seguridad? |
User | Sí. |
Asistente de Google | Muy bien, se activará el sistema de seguridad. |
En el primer turno, debes responder con un desafío 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 solicitud posterior que te envíe Google contendrá el resultado 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 } } ] } }
Ejemplo: Solicitud de confirmación de compra y PIN
En este ejemplo, se muestra un usuario que intenta activar el sistema de seguridad requiriendo una entrada de PIN. El sistema detecta que las ventanas frontal y trasera están abiertas, y le pide al usuario que confirme que la activación debe continuar.
User | Activa el sistema en modo alejado. |
Asistente de Google | ¿Cuál es tu PIN? |
User | 1,234 |
Asistente de Google | Parece que la ventana frontal y la posterior están abiertas. ¿Confirmas que quieres continuar activando el sistema de seguridad en el modo ausente? |
User | Sí. |
Asistente de Google | Muy bien, se activará el sistema de seguridad en el modo ausente |
En el primer turno, debes responder con un desafío pinNeeded
estándar.
{ "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" } }] } }
Luego, Google realiza una solicitud que incluye el PIN proporcionado. Para admitir el segundo turno, debes responder con un desafío ackNeeded
con información adicional, incluido el nivel del grupo objetivo y el informe de estado actual con excepciones de bloqueo.
{ "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 solicitud posterior que te envíe Google contendrá solo el resultado de ack
y no el PIN proporcionado en el primer 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 } } ] } }