Guía del sistema de seguridad de 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 uno 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 correspondiente de la función para obtener detalles de la implementación, como los atributos y estados que debe admitir tu servicio, y cómo compilar respuestas de EXECUTE y QUERY.
Características obligatorias
Estos atributos y comandos son obligatorios, si son aplicables 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.
Rasgos recomendados
Se recomiendan estas características, si corresponde a tu dispositivo. Sin embargo, puedes combinar todos los atributos disponibles para que coincidan mejor con la funcionalidad de tu producto existente.
Requisitos de calidad
- Latencia: Debe ser inferior o igual a 2000 ms.
- Fiabilidad: Debe ser superior o igual al 97%.
Ejemplo de dispositivo: Sistema de seguridad simple
Esta sección contiene cargas útiles de intents de ejemplo que representan un "Sistema de seguridad" común según el tipo de dispositivo y los atributos anteriores. Si agregas o quitas atributos en tu implementación, modifica tus respuestas según corresponda para reflejar esos cambios.
Respuesta de SYNC de muestra
{
"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 QUERY de muestra
{ "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
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": "SUCCESS", "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 los códigos de excepción que informas a través del atributo StatusReport. Las excepciones se pueden informar como bloqueos o no.
- Las excepciones que no generan un bloqueo que se informan con un estado "SUCCESS" indican que la excepción no impidió el armado o el desarmado.
- Las excepciones de bloqueo que se informan con un estado "EXCEPTIONS" indican que el armado o el desarmado se detuvieron debido a estas excepciones.
Estos son algunos de los códigos de excepción que suelen asociarse con los sistemas de seguridad:
doorOpen: Una puerta está 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 no bloqueante
En este ejemplo, se muestra una excepción no bloqueante en la que el sistema de seguridad está activado aunque se informa que una ventana está abierta.
| Usuario | 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
| Usuario | Establece el sistema de seguridad en el nivel alto. |
| Asistente de Google | Se produjo un error al controlar 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": "EXCEPTIONS",
"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 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 seguir activando el sistema cuando haya excepciones activas (por ejemplo, cuando una ventana o puerta está abierta).
En esta situación, es posible que se requiera tanto una entrada de PIN o frase de contraseña, seguida de una confirmación.
Ejemplo: Desafío de acuse de recibo
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 estar activado aunque la puerta principal esté abierta.
| Usuario | Activa el sistema de seguridad. |
| Asistente de Google | La puerta principal está abierta. ¿Seguro que quieres activar el sistema de seguridad? |
| Usuario | Sí. |
| Asistente de Google | Muy bien, activaremos 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 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 acuse de recibo
En este ejemplo, se muestra un usuario que intenta activar el sistema de seguridad que requiere la entrada de un PIN. El sistema detecta que las ventanas delantera y trasera están abiertas y le solicita al usuario que confirme que se debe activar el sistema de alarma.
| Usuario | Activar para alejar. |
| Asistente de Google | ¿Cuál es tu PIN? |
| Usuario | 1234. |
| Asistente de Google | Parece que la ventana delantera y la trasera están abiertas. ¿Confirmas que quieres continuar activando el sistema de seguridad en modo ausente? |
| Usuario | Sí. |
| Asistente de Google | De acuerdo, activaremos 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 realiza un seguimiento con 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 te envíe Google contendrá solo el resultado ack, y no el PIN que proporcionaste 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 } } ] } }