Guía del sistema de seguridad para casas inteligentes
action.devices.types.SECURITYSYSTEM: Los sistemas de seguridad se pueden activar y desactivar. Pueden estar activados en varios niveles de seguridad (por ejemplo, en casa y fuera de ella) y dar 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 atributos y estados que tu servicio debe admitir, y cómo compilar respuestas de EXECUTE y QUERY.
Características obligatorias
Estos rasgos y comandos son obligatorios, si corresponden a tu dispositivo.
Características recomendadas
Se recomiendan estas características, si corresponde, a 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
En esta sección, se incluyen ejemplos de cargas útiles de intents 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 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"
}
}
]
}
}
Respuesta de muestra 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"
}
]
}
}
}
}
Comandos EXECUTE de muestra
Activar brazo
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.Informa excepciones que se activan
Cuando intentes activar o desactivar el sistema, puedes proporcionar contexto adicional mediante códigos de excepción que informes a través de la característica StatusReport. Las excepciones pueden denunciarse como bloqueadas o no bloqueadas.
- Las excepciones sin bloqueo que se informan con el estado "SUCCESS" indican que la excepción no evitó la activación o desactivación.
- Las excepciones de bloqueo informadas con un estado "EXCEPTIONS" indican que la activación o desactivación se detuvo debido a estas excepciones.
Entre los códigos de excepción que suelen asociarse con los sistemas de seguridad, se incluyen los siguientes:
doorOpen: Hay una puerta abierta.windowOpen: Hay una ventana abierta.isOpen: Un sensor detecta que hay algo 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 se activa aunque una ventana se informe como abierta.
| User | Establece el sistema de seguridad en alta seguridad. |
| Asistente de Google | Muy bien, se abrió la ventana frontal. Se activará el sistema de seguridad a un 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 alta seguridad. |
| 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"
}
]
}
}
]
}
}
Activando la autenticación de dos factores
Si el flujo de activación requiere que los usuarios ingresen un PIN a través del 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 puerta esté abierta).
Esta situación puede requerir tanto un ingreso de PIN como de frase de contraseña, seguido de una confirmación.
Ejemplo: Desafío de reconocimiento
En este ejemplo, se muestra un usuario que intenta activar el sistema de seguridad, pero se detecta que una puerta está abierta. El usuario reconoce que el sistema de seguridad debe activarse a pesar de que 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, activando el sistema de seguridad. |
En el primer turno, deberías 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 de 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: PIN y desafío de confirmación
En este ejemplo, se muestra un usuario que intenta activar el sistema de seguridad que requiere la entrada del PIN. El sistema detecta que las ventanas delantera y trasera están abiertas y le pide al usuario que confirme que debe activarse.
| User | Activa el dispositivo para que se apague. |
| Asistente de Google | ¿Cuál es su PIN? |
| User | 1234 |
| Asistente de Google | Al parecer, están abiertas la ventana frontal y la trasera. ¿Seguro que quieres continuar activando 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 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 con el PIN proporcionado. Para admitir el segundo giro, debes responder con un desafío ackNeeded con información adicional, incluido el nivel del grupo de destino 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 haga Google solo contendrá el resultado de ack y no el PIN que se proporcionó en el primer giro.
{
"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
}
}
]
}
}