Przewodnik po inteligentnym systemie alarmowym
action.devices.types.SECURITYSYSTEM
– systemy alarmowe mogą być włączane i wyłączane. Urządzenia mogą być wyposażone w różne poziomy bezpieczeństwa (np. w domu i poza domem) i przesyłać informacje o określonych czujnikach, takich jak czujniki wykrywające ruch lub otwarte okno.
Ten typ oznacza, że urządzenie zobaczy ikonę systemu alarmowego oraz pewne powiązane synonimy i aliasy.
Funkcje urządzenia
W dokumentacji odpowiedniej cechy znajdziesz szczegółowe informacje o implementacji, takie jak atrybuty i stany, które powinna obsługiwać Twoja usługa, oraz sposoby tworzenia odpowiedzi EXECUTE i QUERY.
Wymagane cechy
Te cechy i polecenia są wymagane, jeśli masz je na 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
Te cechy są zalecane, jeśli korzystasz z Twojego urządzenia. Możesz jednak łączyć i dopasowywać różne cechy, aby najlepiej pasowały do dotychczasowych funkcji produktu.
Wymagania dotyczące jakości
- Czas oczekiwania: nie może przekraczać 2000 ms.
- Niezawodność: musi wynosić co najmniej 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 określonych powyżej. Jeśli dodasz lub usuniesz cechy w implementacji, zmodyfikuj 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 poleceń 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łoś wyjątki od włączenia
Gdy próbujesz włączyć lub wyłączyć system, możesz podać dodatkowy kontekst za pomocą kodów wyjątków zgłaszanych za pomocą cechy StatusReport. Wyjątki mogą być zgłaszane jako blokujące lub nieblokujące.
- Wyjątki nieblokujące ze stanem „UDAŁO SIĘ” wskazują, że dany wyjątek nie uniemożliwił włączenia ani wyłączenia alarmu.
- Wyjątki blokowania zgłoszone ze stanem „EXCEPTIONS” oznaczają, że włączanie lub wyłączanie funkcji zostało wstrzymane z powodu tych wyjątków.
Kody wyjątków często powiązane z systemami bezpieczeństwa:
doorOpen
: drzwi są otwarte.windowOpen
: okno jest otwarte.isOpen
: czujnik wykrył, że coś jest otwarte (ale nie wie, czy to drzwi czy okno).
Przykład: wyjątek nieblokujący
Ten przykład przedstawia 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 bezpieczeństwa w systemie alarmowym. |
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 blokowania
Użytkownik | Ustaw wysoki poziom bezpieczeństwa w systemie alarmowym. |
Asystent Google | Podczas sterowania systemem bezpieczeństwa 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": "SUCCESS", "states": { "online": true, "isArmed": false, "currentArmLevel": "L2", "currentStatusReport": [ { "blocking": true, "priority": 0, "statusCode": "windowOpen", "deviceTarget": "sensor_id1" } ] } } ] } }
Włącz weryfikację dwuetapową
Jeśli proces włączania wymaga od użytkowników wpisania kodu PIN w oknie uwierzytelniania dwuskładnikowego, musisz potwierdzić, czy chcą nadal włączać system w przypadku aktywnych wyjątków (np. gdy okno lub drzwi są otwarte).
Ten scenariusz może wymagać zarówno podania kodu PIN, jak i hasła, a następnie potwierdzenia.
Przykład: wyzwanie polegające na podziękowaniu
W tym przykładzie widać, jak użytkownik próbuje włączyć system alarmowy, ale wykryto, że drzwi frontowe 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 wykonaj zadanie 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" } ] } } ] } }
Kolejna prośba do Google wysłana 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 logowanie oparty na kodzie PIN i potwierdzeniu
Ten przykład przedstawia użytkownika próbującego włączyć system alarmowy, który wymaga podania kodu PIN. System wykrywa, że przednie i tylne okna są otwarte, i prosi użytkownika o potwierdzenie, że należy kontynuować włączanie włączania i wyłączania.
Użytkownik | Usuwaj 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 w trybie Poza domem? |
Użytkownik | Tak. |
Asystent Google | OK, włączam system alarmowy w trybie Poza domem |
W pierwszej turze wykonaj standardowe zadanie 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 Google przesyła żądanie zawierające podany kod PIN. Aby umożliwić obsługę drugiej tury, w odpowiedzi prześlij wyzwanie ackNeeded
, podając dodatkowe informacje, m.in. na poziomie grupy docelowej i bieżący raport 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 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 } } ] } }