Guía sobre sistemas de seguridad para la casa inteligente
action.devices.types.SECURITYSYSTEM: Los sistemas de seguridad se pueden activar y desactivar. Se pueden activar 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 de sistema de seguridad y algunos sinónimos y alias relacionados.
Funciones del dispositivo
Consulta la documentación de la característica correspondiente para obtener detalles de implementación, como los atributos y los estados que tu servicio debería admitir, y cómo compilar respuestas de EJECUTE 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 de functionNotSupported en una respuesta QUERY o EXECUTE. Consulta Errores y excepciones para obtener más información.
Traits recomendados
Se recomiendan estas características, si corresponde a tu dispositivo. Sin embargo, puedes mezclar y 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 97%.
Dispositivo de ejemplo: Sistema de seguridad simple
Esta sección contiene cargas útiles de intents de ejemplo que representan un "sistema de seguridad" común en función del tipo de dispositivo y las características anteriores. Si agregas o quitas características en tu implementación, modifica las respuestas según corresponda para reflejar esos cambios.
Ejemplo de respuesta 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"
}
}
]
}
}
ERRORES de dispositivo
Consulta la lista completa de errores y excepciones.Informa excepciones de activación
Cuando intentas activar o desactivar el sistema, puedes proporcionar contexto adicional mediante códigos de excepción que informas a través de la característica StatusReport. Las excepciones se pueden informar como bloqueos o no bloqueos.
- Las excepciones sin bloqueo informadas con un estado "SUCCESS" indican que la excepción no evitó la activación o desactivación.
- Las excepciones de bloqueo informadas con el estado "EXCEPTIONS" indican que la activación o desactivación se detuvo debido a estas excepciones.
Entre los códigos de excepción que se suelen asociar con los sistemas de seguridad, se incluyen los siguientes:
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 una ventana se informa como abierta.
| User | Configura el sistema de seguridad en el nivel de seguridad alto. |
| Asistente de Google | Muy bien, la ventana frontal está abierta. Se activará el sistema de seguridad en un nivel de seguridad 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 | Configura el sistema de seguridad en el nivel de seguridad alto. |
| Asistente de Google | Se produjo un error cuando se controlaba el sistema de seguridad. La ventanilla 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": "EXCEPTIONS",
"states": {
"online": true,
"isArmed": false,
"currentArmLevel": "L2",
"currentStatusReport": [
{
"blocking": true,
"priority": 0,
"statusCode": "windowOpen",
"deviceTarget": "sensor_id1"
}
]
}
}
]
}
}
Activa la autenticación de dos factores
Si tu flujo de activación requiere que los usuarios ingresen un PIN mediante un diálogo de autenticación de dos factores, debes confirmar si desean continuar activando el sistema cuando hay excepciones activas (por ejemplo, cuando una ventana o una puerta está abierta).
Esta situación puede requerir la entrada de un PIN o de una frase de contraseña ambas, seguidas 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 de 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: Desafío de PIN y confirmación de recepción
En este ejemplo, se muestra un usuario que intenta activar el sistema de seguridad y solicita el ingreso 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 debería continuar.
| User | Ábrelo para alejar. |
| Asistente de Google | ¿Cuál es tu PIN? |
| User | 1234. |
| Asistente de Google | Parece que la ventana frontal y la posterior están abiertas. ¿Confirmas que deseas continuar activando el sistema de seguridad en el modo ausente? |
| User | Sí. |
| Asistente de Google | Se activará el sistema de seguridad |
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 envía 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 recibas de Google contendrá solo el resultado ack, y no el PIN que se proporcionó 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
}
}
]
}
}