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 mogą przekazywać informacje z niektórych czujników, takich jak czujnik wykrywający ruch lub otwarte okno.
Ten typ oznacza, że urządzenie otrzyma ikonę systemu bezpieczeństwa oraz kilka powiązanych synonimów i aliasów.
Funkcje urządzenia
Szczegóły implementacji, takie jak atrybuty i stany, które powinna obsługiwać usługa, oraz instrukcje tworzenia odpowiedzi EXECUTE i QUERY znajdziesz w odpowiedniej dokumentacji cech.
Wymagane cechy
Te cechy i polecenia są wymagane na Twoim urządzeniu. Jeśli Twoje urządzenie nie obsługuje tych cech, wpisz kod błędu functionNotSupported w odpowiedzi QUERY lub EXECUTE. Więcej informacji znajdziesz w sekcji 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 dopasowywać obecne funkcje 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 powyższego typu urządzenia i cech. Jeśli dodasz lub usuniesz cechy w swojej implementacji, odpowiednio zmodyfikuj odpowiedzi, aby uwzględnić wprowadzone 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 znajdziesz w dokumentacji
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"
}
}
]
}
}
Urządzenie ERRORS
Zobacz pełną listę błędów i wyjątków.Zgłaszanie wyjątków włączania
Gdy próbujesz włączyć lub wyłączyć system, możesz podać dodatkowy kontekst 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 ze stanem „SUKCES” oznaczają, że wyjątek nie zapobiegał włączeniu ani wyłączeniu alarmu.
- Wyjątki blokowania zgłoszone ze stanem „WYJĄTKI” wskazują, że włączenie lub wyłączenie alarmu zostało zatrzymane z powodu tych wyjątków.
Kody wyjątków często kojarzone z systemami bezpieczeństwa:
doorOpen: drzwi są otwarte.windowOpen: otwarte jest okno.isOpen: czujnik wykrywa, że coś jest otwarte (ale nie wie, czy to drzwi czy 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 | Okno główne 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 | Podczas sterowania systemem alarmowym wystąpił błąd. 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 uzbrojenia wymaga od użytkowników wprowadzenia kodu PIN w oknie uwierzytelniania dwuskładnikowego, musisz potwierdzić, że chcą nadal włączać system w przypadku aktywnych wyjątków (na przykład 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 przyjmuje do wiadomości, że system alarmowy 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 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 użytkownika o potwierdzenie, że należy włączyć włączanie.
| Użytkownik | Odwróć rękę. |
| Asystent Google | Jaki jest Twój kod PIN? |
| Użytkownik | 1234. |
| Asystent Google | Wygląda na to, że przednie i tylne okno są otwarte. Czy na pewno chcesz kontynuować włączanie systemu alarmowego? |
| Użytkownik | Tak. |
| Asystent Google | Włączam system alarmowy na zewnątrz |
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 zapewnić obsługę drugiego etapu, w odpowiedzi należy wysłać zadanie ackNeeded zawierające dodatkowe informacje, m.in. o poziomie grupy docelowej oraz bieżącym raporcie o stanie z wyjątkami blokującymi.
{
"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 od Google do Ciebie będzie zawierać tylko wynik ack, bez kodu PIN podanego 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
}
}
]
}
}