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 sinônimos e aliases relacionados.
Recursos do dispositivo
Consulte a documentação de características correspondente para detalhes de implementação, como atributos e estados aos quais seu serviço precisa oferecer suporte, e como criar respostas de execução 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 tiver suporte a essas características, insira o código de erro de
functionNotSupported em uma resposta de CONSULTA ou EXECUÇÃO. Consulte Erros e exceções para mais informações.
Características recomendadas
Essas características são recomendadas, se aplicáveis ao seu dispositivo. No entanto, você pode combinar todas as características disponíveis para combinar melhor com a funcionalidade atual do seu 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 as 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 no dispositivo
Veja a lista completa de erros e exceções.Informar exceções de armamento
Ao tentar ligar ou desligar o sistema, é possível oferecer mais contexto com códigos de exceção informados pela característica StatusReport. As exceções podem ser informadas como bloqueadoras ou sem bloqueio.
- As exceções sem bloqueio relatadas com o status "SUCESSO" indicam que a exceção não impediu o acionamento ou o desligamento.
- As exceções de bloqueio relatadas com o status "EXCEPTIONS" indicam que a ativação ou desativação foi interrompida 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 é uma porta ou janela.
Exemplo: exceção sem bloqueio
Neste exemplo, mostramos uma exceção sem bloqueio em que o sistema de segurança está 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 no modo de 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": "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 de autenticação de dois fatores, você vai 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 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 a porta da frente é detectada como aberta. O usuário confirma que o sistema de segurança precisa estar ligado, mesmo que a porta da frente esteja aberta.
| User | Ligar o sistema de segurança. |
| Google Assistente | A porta da frente está aberta. Você quer mesmo ligar o sistema de segurança? |
| User | Sim. |
| Google Assistente | Ok, ligando o sistema de segurança. |
Na primeira rodada, 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 próxima solicitação 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 de PIN. O sistema detecta que as janelas dianteiras e traseiras estão abertas e pede para o usuário confirmar que o alarme deve continuar.
| User | Ligar o modo ausente. |
| Google Assistente | Qual é seu PIN? |
| User | 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? |
| User | Sim. |
| Google Assistente | Certo, vamos ligar o sistema de segurança no modo ausente |
Na primeira rodada, 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 curva, 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ê terá apenas o resultado do ack,
e não o PIN fornecido na primeira etapa.
{
"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
}
}
]
}
}