Guia do sistema de segurança residencial inteligente

action.devices.types.SECURITYSYSTEM - Os sistemas de segurança podem ser ligados e desligados. Eles podem ser armados em vários níveis de segurança (por exemplo, em casa e ausente) e podem enviar informações sobre determinados sensores, como um que detecte movimento ou uma janela aberta.

Esse tipo indica que o dispositivo recebe o ícone do sistema de segurança e alguns ícones sinônimos e aliases.

Recursos do dispositivo

Consulte a documentação de característica correspondente para detalhes da implementação, como atributos e estados aos quais seu serviço precisa oferecer suporte, e instruções para criar respostas EXECUTE e QUERY.

Características obrigatórias

Essas características e comandos são obrigatórios, se aplicáveis ao seu dispositivo. Se seu dispositivo não for compatível com essas características, insira o código de erro de functionNotSupported em uma resposta de QUERY ou EXECUTE. Consulte Consulte o artigo Erros e exceções para mais informações.

Essas características são recomendadas, se aplicáveis ao seu dispositivo. No entanto, você pode misturar e combinar todas as características disponíveis para combinar melhor com suas a funcionalidade do produto.

Requisitos de qualidade

  • Latência: precisa ser menor ou igual a 2.000 ms.
  • Confiabilidade:precisa ser maior ou igual a 97%.

Exemplo de dispositivo: sistema de segurança simples

Esta seção contém exemplos de payloads de intents que representam um "Sistema de segurança" com base no tipo de dispositivo e nas características acima. Se você adicionar ou remover características na sua implementação, modifique suas respostas de acordo com essas alterações.

Exemplo de resposta SYNC

Solicitar
. 
{
  "requestId": "6894439706274654512",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}
Resposta
{
  "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"
        }
      }
    ]
  }
}

Exemplo de resposta de QUERY

Solicitar
. 
{
  "requestId": "6894439706274654514",
  "inputs": [
    {
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [
          {
            "id": "123"
          }
        ]
      }
    }
  ]
}
Resposta
{
  "requestId": "6894439706274654514",
  "payload": {
    "devices": {
      "123": {
        "status": "SUCCESS",
        "online": true,
        "isArmed": true,
        "currentArmLevel": "home_key",
        "currentStatusReport": [
          {
            "blocking": false,
            "deviceTarget": "123",
            "priority": 0,
            "statusCode": "lowBattery"
          }
        ]
      }
    }
  }
}

Exemplos de comandos EXECUTE

ArmDisarm

Para mais detalhes sobre os parâmetros de comando, consulte a action.devices.traits.ArmDisarm de referência.

Solicitar
. 
{
  "requestId": "6894439706274654516",
  "inputs": [
    {
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [
          {
            "devices": [
              {
                "id": "123"
              }
            ],
            "execution": [
              {
                "command": "action.devices.commands.ArmDisarm",
                "params": {
                  "arm": true,
                  "armLevel": "away_key"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
Resposta
{
  "requestId": "6894439706274654516",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "isArmed": true,
          "currentArmLevel": "away_key"
        }
      }
    ]
  }
}

ERROS no dispositivo

Veja a lista completa erros e exceções.

Informar exceções de armamento

Ao tentar ligar ou desligar o sistema, você pode fornecer contexto com códigos de exceção que você relatar pela característica StatusReport. As exceções podem ser informadas como bloqueadoras ou sem bloqueio.

  • Exceções sem bloqueio relatadas com "SUCESSO" indicam que a exceção não impediu o ligar nem o desligamento.
  • Exceções de bloqueio relatadas com "EXCEPTIONS" os status indicam que ligar ou o desligamento foi interrompido por causa dessas exceções.

Os códigos de exceção comumente associados a sistemas de segurança incluem:

  • doorOpen: uma porta está aberta.
  • windowOpen: uma janela está aberta.
  • isOpen: um sensor detecta que algo está aberto, mas não sabe se for uma porta ou janela).
.

Exemplo: exceção sem bloqueio

Neste exemplo, mostramos uma exceção sem bloqueio em que o sistema ligado, mesmo que uma janela seja informada como aberta.

Usuário Definir o sistema de segurança como alta segurança.
Google Assistente Ok, a janela da frente está aberta. Ligando o sistema de segurança no modo de alta segurança.
Solicitar
. 
{
    "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"
            }
          }]
        }]
      }
    }]
  }
Resposta
{
    "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"
              }
            ]
          }
        }
      ]
    }
  }

Exemplo: exceção de bloqueio

Usuário Definir o sistema de segurança como alta segurança.
Google Assistente Ocorreu um erro para controlar o sistema de segurança. A janela da frente está aberta.
Solicitar
. 
{
    "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"
            }
          }]
        }]
      }
    }]
  }
Resposta 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"
              }
            ]
          }
        }
      ]
    }
  }

Ligar com a autenticação de dois fatores

Se o fluxo de ativação exigir que os usuários insiram um PIN por uma Caixa de diálogo da autenticação de dois fatores você deve confirmar se eles gostariam de continuar ligando o sistema quando há exceções (por exemplo, quando uma janela ou porta está aberta).

Esse cenário pode exigir uma entrada tanto de PIN quanto de senha longa, seguida de uma confirmação.

Exemplo: desafio de reconhecimento

Este exemplo mostra um usuário tentando ligar o sistema de segurança, mas uma a porta da frente é detectada como aberta. O usuário reconhece que a segurança o sistema precisa estar ligado mesmo que a porta da frente esteja aberta.

Usuário Ligar o sistema de segurança.
Google Assistente A porta da frente está aberta. Você quer mesmo ligar o sistema de segurança?
Usuário Sim.
Google Assistente Ok, ligando o sistema de segurança da nuvem.

Na primeira rodada, você deve responder com um desafio ackNeeded.

Solicitação 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
            }
          }]
        }]
      }
    }]
  }
Resposta 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"
              }
            ]
          }
        }
      ]
    }
  }

A próxima solicitação do Google a você terá o resultado ack.

Solicitação 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
            }
          }]
        }]
      }
    }]
  }
Resposta
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "SUCCESS",
          "states": {
            "isArmed": true
          }
        }
      ]
    }
  }

Exemplo: PIN e desafio de confirmação

Este exemplo mostra um usuário tentando ligar o sistema de segurança que exige a entrada de PIN. O sistema detecta que as janelas dianteiras e traseiras estão abertas e pede para o usuário confirmar e que o acionamento deve prosseguir.

Usuário Ligar o modo ausente.
Google Assistente Qual é seu PIN?
Usuário 1234.
Google Assistente Parece que a janela da frente e a janela traseira estão abertas. Você quer mesmo continuar? desligando o sistema de segurança?
Usuário Sim.
Google Assistente Ok, ligando o o sistema de segurança

Na primeira rodada, você deve responder com um desafio pinNeeded padrão.

Solicitação 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
          }
        }]
      }]
    }
  }]
}
Resposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["456"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Em seguida, o Google envia uma solicitação com o PIN fornecido. Para apoiar na segunda rodada, você deve responder com um desafio ackNeeded com informações adicionais, incluindo o nível do grupo desejado e o relatório de status atual com exceções de bloqueio.

Solicitação 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"
          }
        }]
      }]
    }
  }]
}
Resposta
{
  "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"
      }
    }]
  }
}

A próxima solicitação do Google a você terá apenas o resultado ack. e não o PIN fornecido na primeira etapa.

Solicitação 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
          }
        }]
      }]
    }
  }]
}
Resposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "isArmed": true
        }
      }
    ]
  }
}