Przewodnik po systemie bezpieczeństwa inteligentnego domu
action.devices.types.SECURITYSYSTEM – systemy alarmowe mogą być włączane i wyłączane. Mogą być włączane na różnych poziomach bezpieczeństwa (np. w domu i Poza domem) oraz przekazują informacje z niektórych czujników, takich jak czujnik wykrywający ruch lub otwarte okno.
Ten typ oznacza, że na urządzeniu pojawia się ikona systemu bezpieczeństwa synonimy i aliasy.
Funkcje urządzenia
Zapoznaj się z dokumentacją dotyczącą cech, aby: szczegóły implementacji, takie jak atrybuty i stany, które powinna obsługiwać Twoja usługa, oraz sposób kompilować odpowiedzi EXECUTE i QUERY.
Wymagane cechy
Te cechy i polecenia są wymagane w przypadku Twojego
urządzenia. Jeśli Twoje urządzenie nie obsługuje tych cech, wpisz kod błędu
functionNotSupported w odpowiedzi QUERY lub EXECUTE. Zobacz
Więcej informacji znajdziesz w artykule Błędy i wyjątki.
Zalecane cechy
Są one zalecane (jeśli mają zastosowanie do Twojego urządzenia). Możesz jednak dowolnie łączyć ze sobą wszystkie cechy, aby jak najlepiej dopasować funkcji produktu.
Wymagania dotyczące jakości
- Czas oczekiwania: nie może przekraczać 2000 ms.
- Miarodajność: wartość nie może być mniejsza niż 97%.
Przykład urządzenia: prosty system alarmowy
Ta sekcja zawiera przykładowe ładunki intencji reprezentujące wspólny „system zabezpieczeń” na podstawie typu urządzenia i cech wymienionych powyżej. Jeśli dodasz lub usuniesz cechy swojej implementacji, odpowiednio zmodyfikuj swoje odpowiedzi, by odzwierciedlić te zmiany.
Przykładowa odpowiedź 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"
}
}
]
}
}
Przykładowa odpowiedź na zapytanie 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"
}
]
}
}
}
}
Przykładowe polecenia EXECUTE
ArmDisarm
Więcej informacji o parametrach polecenia:
zobacz
action.devices.traits.ArmDisarm
odwołania.
{
"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"
}
}
]
}
}
Urządzenie ERRORS
Zobacz pełną listę błędów i wyjątków.Zgłaszanie wyjątków włączania
Przy próbie włączenia lub wyłączenia systemu można podać dodatkowe kontekstu za pomocą kodów wyjątków. które zgłaszasz za pomocą cechy StatusReport. Wyjątki mogą być zgłaszane jako blokujące lub nieblokujące.
- Wyjątki nieblokujące zgłoszone z komunikatem „SUKCES” wskazuje, że wyjątek nie uniemożliwił włączenia ani wyłączenia alarmu.
- Wyjątki blokowania zgłoszone z wartością „EXCEPTIONS” wskazuje, że uzbrojenie lub wyłączenie z powodu tych wyjątków zostało zatrzymane.
Kody wyjątków często kojarzone z systemami bezpieczeństwa:
doorOpen: drzwi są otwarte.windowOpen: otwarte jest okno.isOpen: czujnik wykrył, że coś jest otwarte (ale nie wie (jeśli chodzi o drzwi lub okno).
Przykład: wyjątek nieblokujący
Ten przykład pokazuje nieblokujący wyjątek, w którym system alarmowy jest włączony, mimo że okno zostało zgłoszone jako otwarte.
| Użytkownik | Ustaw wysoki poziom zabezpieczeń systemu alarmowego. |
| Asystent Google | OK, przednie okno jest otwarte. Włączam wysoki poziom bezpieczeństwa w systemie alarmowym. |
{
"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"
}
]
}
}
]
}
}
Przykład: wyjątek blokujący
| Użytkownik | Ustaw wysoki poziom zabezpieczeń systemu alarmowego. |
| Asystent Google | Wystąpił błąd sterowanie systemem alarmowym. Frontowe okno jest otwarte. |
{
"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"
}
]
}
}
]
}
}
Włącz uwierzytelnianie dwuskładnikowe
Jeśli proces włączania obsługi wymaga od użytkowników wpisania kodu PIN w Two-factor authentication, musisz potwierdzić, że użytkownik chce nadal włączać system, gdy są wyjątków (np. gdy okno lub drzwi są otwarte).
W tym scenariuszu może być wymagane podanie zarówno kodu PIN, jak i hasła, a następnie potwierdzenia.
Przykład: test zabezpieczający
Ten przykład pokazuje, jak użytkownik próbuje włączyć system alarmowy, ale wykryto, że drzwi wejściowe są otwarte. Użytkownik rozumie, że zabezpieczenia system powinien być włączony, mimo że drzwi wejściowe są otwarte.
| Użytkownik | Włącz system alarmowy. |
| Asystent Google | Drzwi frontowe są otwarte. Czy na pewno chcesz włączyć system alarmowy? |
| Użytkownik | Tak. |
| Asystent Google | OK, włączam przez system alarmowy. |
W pierwszej turze musisz odpowiedzieć, używając wyzwania 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"
}
]
}
}
]
}
}
Kolejne zapytanie od Google do Ciebie będzie zawierać wynik 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
}
}
]
}
}
Przykład: test zabezpieczający z kodem PIN i potwierdzenie
Ten przykład pokazuje, jak użytkownik próbuje włączyć system alarmowy wymagający podania kodu PIN. System wykrywa, że przednie i tylne okna są otwarte, i prosi o potwierdzenie powinno być kontynuowane.
| Użytkownik | Odwróć rękę. |
| Asystent Google | Jaki jest Twój kod PIN? |
| Użytkownik | 1234. |
| Asystent Google | Wygląda na to, a przednie i tylne okna. Czy na pewno chcesz kontynuować Włączyć system alarmowy w tryb Poza domem? |
| Użytkownik | Tak. |
| Asystent Google | OK, włączam system alarmowy na Poza domem |
W pierwszej turze musisz odpowiedzieć standardowym wyzwaniem pinNeeded.
{
"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"
}
}]
}
}
Następnie przesyłamy żądanie zawierające podany kod PIN. Aby pomóc
w drugiej turze musisz odpowiedzieć w ramach wyzwania ackNeeded, podając:
zawiera dodatkowe informacje, m.in. na poziomie grupy docelowej, a także bieżący raport o stanie zawierający
blokujących wyjątki.
{
"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"
}
}]
}
}
Kolejne żądanie Google do Ciebie będzie zawierać tylko wynik ack,
a nie kod PIN podany w pierwszej turze.
{
"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
}
}
]
}
}