Guia do sistema de segurança para casas inteligentes
action.devices.types.SECURITYSYSTEM
: os sistemas de segurança podem ser ligados e desligados. Eles podem ser ligados em vários níveis de segurança (por exemplo, "Em casa" e "Ausente") e enviar informações sobre determinados sensores, como um sensor que detecta movimento ou uma janela aberta.
Esse tipo indica que o dispositivo recebe o ícone do sistema de segurança e alguns sinônimos e aliases relacionados.
Recursos do dispositivo
Consulte a documentação de característica correspondente para conferir detalhes da implementação, como atributos e estados a que seu serviço precisa oferecer suporte e como criar respostas de EXECUTE e CONSULTA.
Características obrigatórias
Essas características e comandos são obrigatórios, se aplicáveis ao seu
dispositivo. Se o dispositivo não oferecer suporte a essas características, insira o código de erro de
functionNotSupported
em uma resposta QUERY ou EXECUTE. Consulte Erros e exceções para mais informações.
Características recomendadas
Estas características são recomendadas, se aplicável ao seu dispositivo. No entanto, é possível combinar todas as características disponíveis para combinar melhor com a funcionalidade atual 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 intent que representam um "Sistema de segurança" comum 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 para refletir essas alterações.
Exemplo de resposta 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" } } ] } }
Exemplo de resposta 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" } ] } } } }
Exemplos de comandos EXECUTE
ArmDisarm
Para mais detalhes sobre os parâmetros de comando,
consulte a
referência
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" } } ] } }
ERROS DO DISPOSITIVO
Veja a lista completa de erros e exceções.Informar exceções de armamento
Ao tentar ligar ou desligar o sistema, você pode fornecer mais contexto usando códigos de exceção informados pela característica StatusReport. As exceções podem ser relatadas como de bloqueio ou sem bloqueio.
- As exceções sem bloqueio relatadas com o status "SUCCESS" indicam que a exceção não impediu o ligar ou desligar.
- As exceções de bloqueio informadas com um status "EXCEPTIONS" indicam que o ligar ou desligar foi interrompido devido a essas exceções.
Os códigos de exceção que sã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 é uma porta ou janela.
Exemplo: exceção sem bloqueio
Este exemplo mostra uma exceção sem bloqueio em que o sistema de segurança é ligado mesmo que uma janela seja informada como aberta.
User | 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 com alta segurança. |
{ "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" } ] } } ] } }
Exemplo: exceção de bloqueio
User | Definir o sistema de segurança como "alta segurança". |
Google Assistente | Ocorreu um erro ao controlar o sistema de segurança. A janela da frente está aberta. |
{ "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" } ] } } ] } }
Ligando com a autenticação de dois fatores
Se o fluxo de ligar exigir que os usuários insiram um PIN em uma caixa de diálogo de autenticação de dois fatores, é necessário confirmar se eles querem continuar ligando o sistema quando houver exceções ativas, por exemplo, quando uma janela ou porta estiver aberta.
Esse cenário pode exigir um PIN ou uma entrada de senha longa, seguidos por uma confirmação.
Exemplo: desafio de reconhecimento
Este exemplo mostra um usuário tentando ligar o sistema de segurança, mas uma porta da frente foi detectada como aberta. O usuário reconhece que o sistema de segurança precisa ser ligado mesmo com a porta da frente aberta.
User | Ligar o sistema de segurança. |
Google Assistente | A porta da frente está aberta. Tem certeza de que deseja ligar o sistema de segurança? |
User | Sim. |
Google Assistente | Certo, ligando o sistema de segurança. |
Na primeira vez, você deve responder com um desafio 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" } ] } } ] } }
A solicitação seguinte do Google a você terá o 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 } } ] } }
Exemplo: PIN e desafio de confirmação
Este exemplo mostra um usuário tentando ligar o sistema de segurança que exige a entrada do PIN. O sistema detecta se as janelas frontal e traseira estão abertas e pede que o usuário confirme que o alarme precisa prosseguir.
User | Ligar no modo "Ausente". |
Google Assistente | Qual é seu PIN? |
User | 1234. |
Google Assistente | Parece que as janelas frontal e traseira estão abertas. Você quer mesmo continuar ligando o sistema de segurança no modo ausente? |
User | Sim. |
Google Assistente | Certo, Ligar o sistema de segurança no modo ausente |
Na primeira vez, você deve responder com um desafio pinNeeded
padrão.
{ "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" } }] } }
O Google faz o acompanhamento com uma solicitação que contém o PIN fornecido. Para que haja compatibilidade
com o segundo turno, você precisa responder com um desafio ackNeeded
com
mais informações, incluindo o nível do grupo de destino e o relatório de status atual com
exceções de bloqueio.
{ "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" } }] } }
A próxima solicitação do Google a você conterá apenas o resultado ack
, e não o PIN fornecido na primeira curva.
{ "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 } } ] } }