Руководство по системе безопасности умного дома
action.devices.types.SECURITYSYSTEM
— Системы безопасности могут быть поставлены на охрану и сняты с охраны. Они могут быть активированы на нескольких уровнях безопасности (например, дома и в гостях) и могут сообщать информацию об определенных датчиках, таких как датчик, обнаруживающий движение или открытое окно.
Этот тип указывает, что устройство получает значок системы безопасности и некоторые связанные с ним синонимы и псевдонимы.
Возможности устройства
Подробности реализации, такие как атрибуты и состояния, которые должна поддерживать ваша служба, а также способы построения ответов EXECUTE и QUERY см. в соответствующей документации по трейтам.
Требуемые черты
Эти свойства и команды являются обязательными, если они применимы к вашему устройству.
Рекомендуемые черты
Эти характеристики рекомендуются, если применимы к вашему устройству. Тем не менее, вы можете смешивать и сочетать все доступные черты, чтобы наилучшим образом соответствовать функциональным возможностям вашего существующего продукта.
Требования к качеству
- Задержка: должна быть меньше или равна 2000 мс .
- Надежность: должна быть больше или равна 97% .
Пример устройства: простая система безопасности
Этот раздел содержит примеры полезной нагрузки намерения, представляющей общую «систему безопасности» на основе типа устройства и характеристик, указанных выше. Если вы добавляете или удаляете черты в своей реализации, измените свои ответы соответствующим образом, чтобы отразить эти изменения.
Пример ответа 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" } } ] } }
Пример ответа на ЗАПРОС
{ "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" } ] } } } }
Примеры команд EXECUTE
Постановка на охрану
Дополнительные сведения о параметрах команды см. в справочнике 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" } } ] } }
ОШИБКИ устройства
См. полный список ошибок и исключений .Сообщить об исключениях при постановке на охрану
При попытке поставить или снять систему с охраны вы можете предоставить дополнительный контекст с помощью кодов исключений , о которых вы сообщаете через трейт StatusReport . Исключения могут быть зарегистрированы как блокирующие или неблокирующие.
- Неблокирующие исключения , о которых сообщается со статусом «УСПЕХ», указывают на то, что исключение не помешало постановке или снятию с охраны.
- Блокирующие исключения , о которых сообщается со статусом «ИСКЛЮЧЕНИЯ», указывают на то, что постановка на охрану или снятие с охраны были остановлены из-за этих исключений.
Коды исключений, которые обычно связаны с системами безопасности, включают:
-
doorOpen
: Дверь открыта. -
windowOpen
: Окно открыто. -
isOpen
: датчик обнаруживает, что что-то открыто (но не знает, дверь это или окно).
Пример: неблокирующее исключение
В этом примере показано неблокирующее исключение, когда система безопасности поставлена на охрану, даже если окно сообщается как открытое.
Пользователь | Установите систему безопасности на высокий уровень безопасности. |
Google Ассистент | Хорошо, переднее окно открыто. Постановка системы безопасности на высокий уровень безопасности. |
{ "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" } ] } } ] } }
Пример: исключение блокировки
Пользователь | Установите систему безопасности на высокий уровень безопасности. |
Google Ассистент | Произошла ошибка управления системой безопасности. Переднее окно открыто. |
{ "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" } ] } } ] } }
Вооружение с двухфакторной аутентификацией
Если ваш процесс постановки на охрану требует, чтобы пользователи вводили PIN-код через диалоговое окно двухфакторной аутентификации , вы должны подтвердить, хотят ли они продолжать ставить систему на охрану при наличии активных исключений (например, при открытии окна или двери).
В этом сценарии может потребоваться ввод PIN-кода или парольной фразы с последующим подтверждением.
Пример: вызов подтверждения
В этом примере показан пользователь, пытающийся включить систему безопасности, но входная дверь определяется как открытая. Пользователь подтверждает, что система безопасности должна быть поставлена на охрану, даже если входная дверь открыта.
Пользователь | Включите систему безопасности. |
Google Ассистент | Входная дверь открыта. Вы уверены, что хотите включить систему безопасности? |
Пользователь | Да. |
Google Ассистент | Ладно, включаю систему безопасности. |
В первый ход вы должны ответить вызовом 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" } ] } } ] } }
Последующий запрос от Google к вам будет содержать результат 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 } } ] } }
Пример: ПИН-код и вызов подтверждения
В этом примере показана попытка пользователя включить систему безопасности, требующую ввода PIN-кода. Система определяет, что переднее и заднее окна открыты, и просит пользователя подтвердить, что следует продолжить постановку на охрану.
Пользователь | Рука прочь. |
Google Ассистент | Какой у вас PIN-код? |
Пользователь | 1234. |
Google Ассистент | Похоже, что переднее окно и заднее окно открыты. Вы уверены, что хотите продолжить постановку системы безопасности на охрану? |
Пользователь | Да. |
Google Ассистент | Ладно, включаю систему безопасности. |
В первую очередь следует ответить стандартным вызовом pinNeeded
.
{ "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" } }] } }
Затем Google отправляет запрос, содержащий предоставленный PIN-код. Чтобы поддержать вторую очередь, вы должны ответить вызовом ackNeeded
с дополнительной информацией, включая целевой уровень руки и текущий отчет о состоянии с блокирующими исключениями.
{ "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" } }] } }
Последующий запрос от Google к вам будет содержать только результат ack
, а не предоставленный в первую очередь PIN.
{ "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 } } ] } }