Guía del sistema de seguridad para el hogar inteligente
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 uno que detecte movimiento o una ventana abierta.
Este tipo indica que el dispositivo obtiene el ícono del sistema de seguridad y algunos sinónimos y sinónimos relacionados.
Funciones del dispositivo
Consulta la documentación de características correspondiente para obtener detalles de implementación, como atributos y estados que tu servicio debe admitir, y cómo compilar respuestas de EXECUTE y QUERY.
Características obligatorias
Estas características y comandos son necesarios si corresponden a tu dispositivo.
Características recomendadas
Recomendamos estas características, si se aplican 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 97%.
Ejemplo de dispositivo: Sistema de seguridad simple
Esta sección contiene cargas útiles de intent de ejemplo que representan un "sistema de seguridad" común según el tipo de dispositivo y las características anteriores. Si agregas o quitas rasgos 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 de EXECUTE de muestra
Activar la alarma
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.Informar excepciones activadas
Cuando intentes activar o desactivar el sistema, puedes proporcionar contexto adicional mediante códigos de excepciones que informes a través de la característica StatusReport. Se pueden informar excepciones como bloqueos o no bloqueos.
- Las excepciones sin bloqueo informadas con el estado "SUCCESS" indican que la excepción no evitó que se activen o desactiven.
- 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 comúnmente asociados con los sistemas de seguridad, se incluyen los siguientes:
doorOpen: Hay una puerta abierta.windowOpen: Está abierta una ventana.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 a pesar de que una ventana se informa como abierta.
| User | Establece el sistema de seguridad en alto nivel. |
| Asistente de Google | Muy bien, la ventana frontal está abierta. Se activará el sistema de seguridad para garantizar 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 alto nivel. |
| Asistente de Google | Se produjo un error al controlar el sistema de seguridad. La ventana principal 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 de la 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 puerta está abierta).
En este caso, es posible que se requiera un PIN o una entrada de frase de contraseña, seguido de una confirmación de recepción.
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, activando 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 recibas de 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 y que requiere una entrada de PIN. El sistema detecta que las ventanas frontal y posterior están abiertas y le pide al usuario que reconozca que se debe activar la activación.
| User | Activa el brazo para alejarte. |
| Asistente de Google | ¿Cuál es tu PIN? |
| User | 1234. |
| Asistente de Google | Parece que la ventana principal y la trasera están abiertas. ¿Estás seguro de que deseas continuar activando el sistema de seguridad para que desaparezca? |
| User | Sí. |
| Asistente de Google | Está bien, desactivando 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"
}
}]
}
}
A continuación, Google realiza un seguimiento de la solicitud que contiene el PIN proporcionado. Para admitir la segunda vuelta, 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 solo contendrá el resultado de ack y no el PIN proporcionado 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
}
}
]
}
}