Руководство по системе безопасности умного дома

action.devices.types.SECURITYSYSTEM — системы безопасности можно ставить и снимать с охраны. Они могут быть поставлены на охрану на нескольких уровнях безопасности (например, дома и на улице) и могут сообщать информацию об определенных датчиках, например датчике, обнаруживающем движение или открытое окно.

Этот тип означает, что на устройстве отображается значок «Система безопасности» и некоторые связанные с ним синонимы и псевдонимы.

Возможности устройства

Обратитесь к соответствующей документации по типажу для получения подробной информации о реализации, такой как атрибуты и состояния, которые ваша служба должна поддерживать, а также о том, как создавать ответы EXECUTE и QUERY.

Требуемые черты

Эти характеристики и команды обязательны, если они применимы к вашему устройству. Если ваше устройство не поддерживает эти функции, введите код ошибки functionNotSupported в ответе QUERY или EXECUTE. Дополнительную информацию см. в разделе «Ошибки и исключения» .

Эти характеристики рекомендуются, если они применимы к вашему устройству. Однако вы можете комбинировать все доступные характеристики, чтобы наилучшим образом соответствовать существующей функциональности вашего продукта.

Требования к качеству

  • Задержка: должна быть меньше или равна 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"
        }
      }
    ]
  }
}

Пример ответа 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"
          }
        ]
      }
    }
  }
}

Примеры команд 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"
            }
          }]
        }]
      }
    }]
  }
Ответ 2 
{
    "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"
              }
            ]
          }
        }
      ]
    }
  }

Включение двухфакторной аутентификации

Если ваш процесс постановки на охрану требует, чтобы пользователи вводили PIN-код через диалоговое окно двухфакторной аутентификации , вы должны подтвердить, хотят ли они продолжать ставить систему на охрану при наличии активных исключений (например, когда окно или дверь открыты).

В этом сценарии может потребоваться ввод PIN-кода или парольной фразы с последующим подтверждением.

Пример: запрос подтверждения

В этом примере показано, как пользователь пытается поставить систему безопасности на охрану, но входная дверь обнаруживается как открытая. Пользователь признает, что система безопасности должна быть поставлена ​​на охрану, даже если входная дверь открыта.

Пользователь Включите систему безопасности.
Google Ассистент Входная дверь открыта. Вы уверены, что хотите поставить систему безопасности на охрану?
Пользователь Да.
Google Ассистент Хорошо, включаем систему безопасности.

В первую очередь вам следует ответить вызовом ackNeeded .

Запрос 1 
{
    "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
            }
          }]
        }]
      }
    }]
  }
Ответ 2
{
    "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 .

Запрос 2 
{
    "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-код и запрос подтверждения

В этом примере показан пользователь, пытающийся поставить систему безопасности на охрану, требующую ввода PIN-кода. Система обнаруживает, что переднее и заднее окна открыты, и просит пользователя подтвердить необходимость постановки на охрану.

Пользователь Рука, чтобы уйти.
Google Ассистент Какой у тебя PIN-код?
Пользователь 1234.
Google Ассистент Похоже, переднее и заднее окна открыты. Вы уверены, что хотите продолжить постановку системы безопасности на охрану?
Пользователь Да.
Google Ассистент Хорошо, включаю систему безопасности, чтобы уйти.

В первую очередь вам следует ответить стандартным вызовом pinNeeded .

Запрос 1 
{
  "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 с дополнительной информацией, включая целевой уровень постановки на охрану и отчет о текущем состоянии с исключениями блокировки.

Запрос 2 
{
  "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-код, предоставленный в первую очередь.

Запрос 3 
{
  "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
        }
      }
    ]
  }
}