Przewodnik po systemie zabezpieczeń w inteligentnym domu
action.devices.types.SECURITYSYSTEM – systemy alarmowe można włączać i wyłączać. Można je włączać na różnych poziomach bezpieczeństwa (np. w domu i poza domem) oraz przekazywać informacje o określonych czujnikach, np. o czujniku ruchu lub otwartym oknie.
Ten typ wskazuje, że urządzenie ma ikonę systemu zabezpieczeń oraz niektóre powiązane synonimy i aliasy.
Funkcje urządzenia
Szczegółowe informacje o wdrożeniu, takie jak atrybuty i stany, które powinna obsługiwać usługa, oraz sposób tworzenia odpowiedzi na wywołania EXECUTE i QUERY, znajdziesz w odpowiedniej dokumentacji atrybutu.
Wymagane cechy
Te cechy i polecenia są wymagane, jeśli są dostępne na Twoim urządzeniu. Jeśli urządzenie nie obsługuje tych atrybutów, wpisz kod błędu functionNotSupported w odpowiedzi na QUERY lub EXECUTE. Więcej informacji znajdziesz w sekcji Błędy i wyjątki.
Zalecane cechy
Te cechy są zalecane, jeśli są dostępne na Twoim urządzeniu. Możesz jednak dowolnie łączyć wszystkie dostępne cechy, aby jak najlepiej dopasować je do dotychczasowej funkcjonalności produktu.
Wymagania dotyczące jakości
- Opóźnienie: musi być mniejsze lub równe 2000 ms.
- Niezawodność: musi być większa lub równa 97%.
Przykładowe urządzenie: prosty system zabezpieczeń
Ta sekcja zawiera przykładowe dane intencji przedstawiające typowy „system bezpieczeństwa” na podstawie typu urządzenia i właściwości wymienionych powyżej. Jeśli w swojej implementacji dodasz lub usuniesz cechy, odpowiednio zmodyfikuj odpowiedzi, aby uwzględnić 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
{ "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" } } ] } }
BŁĘDY urządzenia
Zobacz pełną listę błędów i wyjątków.Zgłaszanie wyjątków dotyczących uzbrojenia
Podczas próby uzbrojenia lub rozbrojenia systemu możesz podać dodatkowy kontekst za pomocą kodów wyjątków, które zgłaszasz za pomocą atrybutu StatusReport. Wyjątki mogą być zgłaszane jako blokujące lub nieblokujące.
- Wyjątki nieblokujące zgłoszone ze stanem „SUCCESS” wskazują, że wyjątek nie uniemożliwił uzbrojenia ani rozbrojenia.
- Wyjątki dotyczące blokowania zgłoszone ze stanem „EXCEPTIONS” wskazują, że uzbrajanie lub rozbrojenie zostało zatrzymane z powodu tych wyjątków.
Kody wyjątków, które są często powiązane z systemami zabezpieczeń:
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 pokazuje wyjątek nieblokujący, w którym system alarmowy jest włączony, mimo że okno jest zgłoszone jako otwarte.
| Użytkownik | Ustaw system alarmowy na wysoki poziom bezpieczeństwa. |
| Asystent Google | Okno przednie jest otwarte. Włączam system alarmowy z wysokim poziomem bezpieczeństwa. |
{
"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 dotyczący blokowania
| Użytkownik | Ustaw system alarmowy na wysoki poziom bezpieczeństwa. |
| Asystent Google | Wystąpił błąd podczas sterowania systemem zabezpieczeń. Okno frontowe 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łączanie uwierzytelniania dwuskładnikowego
Jeśli proces uzbrajania wymaga od użytkowników wpisania kodu PIN w oknie uwierzytelniania dwuskładnikowego, musisz zapytać, czy chcą kontynuować uzbrajanie systemu, gdy są aktywne wyjątki (np. gdy okno lub drzwi są otwarte).
W tym przypadku może być wymagane podanie kodu PIN lub hasła, a następnie potwierdzenia.
Przykład: potwierdzenie przyjęcia
Ten przykład pokazuje, jak użytkownik próbuje włączyć system alarmowy, ale drzwi wejściowe są otwarte. Użytkownik potwierdza, że system alarmowy powinien być włączony, nawet jeśli drzwi wejściowe są otwarte.
| Użytkownik | Włącz system alarmowy. |
| Asystent Google | Drzwi frontowe są otwarte. Czy na pewno chcesz uzbroić system zabezpieczeń? |
| Użytkownik | Tak. |
| Asystent Google | Ok, włączam system alarmowy. |
W pierwszej turze powinieneś odpowiedzieć wyzwaniem 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 żądanie wysłane do Ciebie przez Google 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: wyzwanie dotyczące kodu PIN i potwierdzenie
Ten przykład pokazuje użytkownika, który próbuje włączyć system zabezpieczeń wymagający podania kodu PIN. System wykrywa, że okna przednie i tylne są otwarte, i prosi użytkownika o potwierdzenie, że chce kontynuować uzbrajanie.
| Użytkownik | Włącz tryb nieobecności. |
| Asystent Google | Jaki jest Twój kod PIN? |
| Użytkownik | 1234. |
| Asystent Google | Wygląda na to, że okno przednie i tylne są otwarte. Czy na pewno chcesz kontynuować uzbrajanie systemu bezpieczeństwa w tryb opuszczony? |
| Użytkownik | Tak. |
| Asystent Google | Włączam system alarmowy na tryb „w drodze”. |
W pierwszej turze powinieneś 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 Google wysyła prośbę z podanym kodem PIN. Aby umożliwić drugą turę, odpowiedz na wyzwanie ackNeeded, podając dodatkowe informacje, w tym poziom grupy docelowej i bieżący raport stanu 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 wysłane do Ciebie przez Google będzie zawierać tylko wynik ack, a nie kod PIN podany w pierwszym żądaniu.
{ "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 } } ] } }