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 informar 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 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 para 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
Te recomendamos que agregues estas características a tu dispositivo, si corresponde. Sin embargo, puedes combinar todas las características disponibles para adaptarlas mejor a las funciones del producto existentes.
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 ejemplos de cargas útiles de intents que representan un "sistema de seguridad" común basado en el tipo y las características de dispositivo mencionados anteriormente. Si agregas o quitas rasgos en tu implementación, modifica las 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" } } ] } }
Respuesta de muestra 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" } ] } } } }
Ejemplo 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" } } ] } }
Dispositivo ERRORS
Consulta la lista completa de errores y excepciones.Cómo informar excepciones de activación
Cuando intentas activar o desactivar el sistema, puedes proporcionar contexto adicional mediante 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 informan 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.
Estos son algunos de 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 a pesar de que una ventana se informa como abierta.
User | Establece el sistema de seguridad en el nivel alto. |
Asistente de Google | Muy bien, la ventana delantera está abierta. Se activará el sistema de seguridad en el nivel alto. |
{ "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 el 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 hay excepciones activas (por ejemplo, cuando hay una ventana o una puerta abiertas).
Esta situación puede requerir ambos, un PIN o una frase de contraseña, seguido de un reconocimiento.
Ejemplo: Desafío de confirmación
En este ejemplo, se muestra a 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 haga 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 posterior están abiertas, y le pide al usuario que confirme que la activación debe continuar.
User | Activa el botón de activación. |
Asistente de Google | ¿Cuál es tu PIN? |
User | 1234. |
Asistente de Google | Al parecer, la ventana frontal y la trasera están abiertas. ¿Confirmas que quieres continuar activando el sistema de seguridad en 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 contiene 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 Google te haga 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 } } ] } }