Guía del sistema de seguridad en la casa inteligente
action.devices.types.SECURITYSYSTEM: Los sistemas de seguridad se pueden activar y desactivar. Se pueden armar en varios niveles de seguridad (por ejemplo, en casa y ausente) y pueden informar 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 del rasgo correspondiente para obtener detalles de implementación, como los atributos y los estados que debe admitir tu servicio, y cómo crear respuestas de EXECUTE y QUERY.
Rasgos obligatorios
Estos rasgos y comandos son obligatorios, si se aplican a tu dispositivo. Si tu dispositivo no admite estos rasgos, ingresa el código de error de functionNotSupported en una respuesta de QUERY o EXECUTE. Consulta Errores y excepciones para obtener más información.
Rasgos sugeridos
Estos rasgos se recomiendan si son aplicables a tu dispositivo. Sin embargo, puedes combinar todos los rasgos disponibles para que coincidan mejor con la funcionalidad existente de tu producto.
Ejemplo de dispositivo: Sistema de seguridad simple
En esta sección, se incluyen cargas útiles de intents de ejemplo que representan un "sistema de seguridad" común según el tipo de dispositivo y los rasgos anteriores. Si agregas rasgos a tu implementación o los quitas, modifica tus 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" } ] } } } }
Comandos de EXECUTE de muestra
ArmDisarm
Para obtener más detalles 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": "PENDING", "states": { "online": true, "isArmed": true, "currentArmLevel": "away_key" } } ] } }
ERRORES del dispositivo
Consulta la lista completa de errores y excepciones.Informa excepciones de armado
Cuando intentes activar o desactivar el sistema, puedes proporcionar contexto adicional a través de códigos de excepción que informes a través del rasgo StatusReport. Las excepciones se pueden informar como bloqueantes o no bloqueantes.
- Las excepciones no bloqueantes 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.
Los códigos de excepción que se asocian comúnmente con los sistemas de seguridad incluyen los siguientes:
doorOpen: Una puerta está abierta.windowOpen: Se abrió una ventana.isOpen: Un sensor detecta que algo está abierto (pero no sabe si es una puerta o una ventana).
Ejemplo: Excepción no bloqueante
En este ejemplo, se muestra una excepción no bloqueante en la que el sistema de seguridad está armado, aunque se informa que una ventana está abierta.
| Usuario | Establece el sistema de seguridad en el nivel de seguridad alto. |
| Asistente de Google | De acuerdo, la ventana delantera está abierta. Se activará el sistema de seguridad en modo de alta 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
| Usuario | Establece el sistema de seguridad en el nivel de seguridad alto. |
| Asistente de Google | Se produjo un error al controlar el sistema de seguridad. La ventana delantera 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"
}
]
}
}
]
}
}Cómo activar la alarma con la autenticación de dos factores
Si tu flujo de armado 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 armando el sistema cuando haya excepciones activas (por ejemplo, cuando una ventana o puerta está abierta).
En este caso, es posible que se requiera tanto el ingreso de un PIN o una frase de contraseña, seguido de una confirmación.
Ejemplo: Desafío de reconocimiento
En este ejemplo, se muestra a un usuario que intenta activar el sistema de seguridad, pero se detecta que la puerta principal está abierta. El usuario reconoce que el sistema de seguridad debe activarse incluso si la puerta principal está abierta.
| Usuario | Activa el sistema de seguridad. |
| Asistente de Google | La puerta principal está abierta. ¿Confirmas que quieres activar el sistema de seguridad? |
| Usuario | Sí. |
| Asistente de Google | De acuerdo, 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
En este ejemplo, se muestra a un usuario que intenta activar el sistema de seguridad y debe ingresar un PIN. El sistema detecta que las ventanas delantera y trasera están abiertas y le pide al usuario que confirme que se debe proceder con el armado.
| Usuario | Activa el modo ausente. |
| Asistente de Google | ¿Cuál es tu PIN? |
| Usuario | 1234. |
| Asistente de Google | Parece que la ventana delantera y la ventana trasera están abiertas. ¿Confirmas que quieres seguir activando el sistema de seguridad como ausente? |
| Usuario | Sí. |
| Asistente de Google | De acuerdo, activando el sistema de seguridad en 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 hace un seguimiento con una solicitud que contiene el PIN proporcionado. Para admitir el segundo turno, debes responder con un desafío ackNeeded que incluya información adicional, como el nivel de brazo 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 solo contendrá el resultado 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 } } ] } }