Guia do sistema de segurança da casa inteligente
action.devices.types.SECURITYSYSTEM
: os sistemas de segurança podem ser ativados e desativados. Eles podem ser ativados em vários níveis de segurança (por exemplo, "Em casa" e "Ausente") e podem informar 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 pseudônimos relacionados.
Recursos do dispositivo
Consulte a documentação de atributo correspondente para detalhes de implementação, como atributos e estados que seu serviço precisa oferecer suporte e como 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 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
Essas características são recomendadas, se aplicável ao seu dispositivo. No entanto, você pode misturar e combinar todas as características disponíveis para corresponder melhor à funcionalidade do produto.
Requisitos de qualidade
- Latência:precisa ser menor ou igual a 2000ms.
- 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 implementação, modifique as respostas para refletir essas mudanças.
Exemplo de resposta de sincronização
{ "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
Confira a lista completa de erros e exceções.Relatar exceções de acionamento
Ao tentar ativar ou desativar o sistema, você pode fornecer mais contexto usando códigos de exceção informados pelo atributo StatusReport. As exceções podem ser informadas como bloqueadoras ou não bloqueadoras.
- Exceções sem bloqueio relatadas com um status "SUCCESS" indicam que a exceção não impediu a ativação ou desativação.
- Exceções de bloqueio relatadas com o status "EXCEPTIONS" indicam que a ativação ou desativação foi interrompida devido a essas 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 é uma porta ou uma janela.
Exemplo: exceção não bloqueante
Este exemplo mostra uma exceção não de bloqueio em que o sistema de segurança é ativado, mesmo que uma janela seja informada como aberta.
Usuário | Definir o sistema de segurança como alta. |
Google Assistente | Ok, a janela da frente está aberta. Ligando o sistema de segurança para segurança alta. |
{
"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
Usuário | Definir o sistema de segurança como alta. |
Google Assistente | Houve 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": "EXCEPTIONS",
"states": {
"online": true,
"isArmed": false,
"currentArmLevel": "L2",
"currentStatusReport": [
{
"blocking": true,
"priority": 0,
"statusCode": "windowOpen",
"deviceTarget": "sensor_id1"
}
]
}
}
]
}
}
Como ativar a autenticação de dois fatores
Se o fluxo de ativação exigir que os usuários insiram um PIN em uma caixa de diálogo de autenticação de dois fatores, você precisa confirmar se eles querem continuar ativando o sistema quando houver exceções ativas (por exemplo, quando uma janela ou porta estiver aberta).
Esse cenário pode exigir ambos, uma entrada de PIN ou frase de acesso, seguida de um aviso.
Exemplo: desafio de confirmação
Este exemplo mostra um usuário tentando ativar o sistema de segurança, mas a porta da frente é detectada como aberta. O usuário reconhece que o sistema de segurança precisa ser ativado, mesmo que a porta da frente esteja aberta.
Usuário | Ativar o sistema de segurança. |
Google Assistente | A porta da frente está aberta. Você tem certeza de que quer ativar o sistema de segurança? |
Usuário | Sim. |
Google Assistente | Ok, acionando 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 subsequente do Google vai conter 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 ativar o sistema de segurança que exige a entrada de um PIN. O sistema detecta que as janelas da frente e de trás estão abertas e pede que o usuário confirme que o acionamento deve continuar.
Usuário | Ligar no nível: |
Google Assistente | Qual é seu PIN? |
Usuário | 1234. |
Google Assistente | Parece que a janela da frente e a de trás estão abertas. Você quer mesmo continuar ativando o sistema de segurança? |
Usuário | Sim. |
Google Assistente | Ok, ligando o sistema de segurança para sair |
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" } }] } }
Em seguida, o Google envia uma solicitação com o PIN fornecido. Para oferecer suporte
à segunda vez, responda com um desafio ackNeeded
com
mais informações, incluindo o nível do braço 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 solicitação subsequente do Google vai conter apenas o resultado ack
,
e não o PIN fornecido na primeira vez.
{ "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 } } ] } }