Przewodnik po inteligentnym systemie alarmowym
action.devices.types.SECURITYSYSTEM – systemy alarmowe mogą być włączone i wyłączone. Możesz włączyć je w kilku poziomach bezpieczeństwa (np. w domu i Poza domem) oraz przesyłać informacje o niektórych czujnikach, takich jak czujnik ruchu lub otwarte okno.
Ten typ oznacza, że urządzenie otrzyma ikonę systemu zabezpieczeń i kilka powiązanych synonimów i aliasów.
Funkcjonalność urządzenia
Zapoznaj się z odpowiednią dokumentacją cech, aby poznać szczegóły 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 mają zastosowanie w przypadku Twojego urządzenia.
Cechy charakterystyczne
Te cechy są zalecane w przypadku urządzeń, z których korzystasz. Możesz swobodnie łączyć ze sobą wszystkie dostępne cechy, aby jak najlepiej dopasować je do istniejących funkcji.
Wymagania dotyczące jakości
- Opóźnienie: nie może przekraczać 2000 ms.
- Niezawodność: musi wynosić co najmniej 97%.
Przykładowe urządzenie: prosty system bezpieczeństwa
Ta sekcja zawiera przykładowe ładunki intencji reprezentujące popularny „system zabezpieczeń” oparte na typach urządzeń i cechach wymienionych powyżej. Jeśli dodasz lub usuniesz cechy w implementacji, odpowiednio dostosuj odpowiedzi.
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
Broń do broni
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łaszaj wyjątki do 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ą atrybutu StatusReport (Stan zgłoszenia). Wyjątki można zgłaszać jako blokujące lub nieblokujące.
- Wyjątki nieblokujące zgłoszone ze stanem „Powodzenie” wskazują, że wyjątek nie uniemożliwił włączenia lub wyłączenia alarmu.
- Wyjątki blokowania ze stanem „WYKLUCZENIA” wskazują, że z powodu tych wyjątków zatrzymanie lub wyłączenie urządzenia zostało wyłączone.
Kody wyjątków, które są często powiązane z systemami bezpieczeństwa, to między innymi:
doorOpen: drzwi są otwarte.windowOpen: okno jest otwarte.isOpen: czujnik wykrywa, że coś jest otwarte (ale nie wie, czy jest to drzwi czy okno).
Przykład: nieblokujący wyjątek
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 zabezpieczeń. |
| Asystent Google | OK, okno przednie jest otwarte. Włączam system alarmowy o wysokim zabezpieczeniach. |
{
"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: blokowanie wyjątku
| Użytkownik | Ustaw system alarmowy na wysoki poziom zabezpieczeń. |
| 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": "SUCCESS",
"states": {
"online": true,
"isArmed": false,
"currentArmLevel": "L2",
"currentStatusReport": [
{
"blocking": true,
"priority": 0,
"statusCode": "windowOpen",
"deviceTarget": "sensor_id1"
}
]
}
}
]
}
}
Włączam uwierzytelnianie dwuskładnikowe
Jeśli w ramach procesu włączania wymagane jest wpisanie kodu PIN w oknie uwierzytelniania dwuskładnikowego, musisz potwierdzić, że system ma nadal włączać system, gdy istnieją aktywne wyjątki (np. gdy otwarte jest okno lub drzwi).
W takim przypadku może być wymagane zarówno wprowadzenie kodu PIN, jak i potwierdzenie.
Przykład: wyzwanie podziękowania
Ten przykład pokazuje, że użytkownik próbuje włączyć system alarmowy, ale drzwi frontowe są wykrywane jako otwarte. Użytkownik przyjmuje do wiadomości, że system alarmowy powinien być włączony, mimo że drzwi frontowe 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. |
Na pierwszym etapie musisz odpowiedzieć na wyzwanie 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 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 PIN i test zabezpieczający
Ten przykład pokazuje, że użytkownik próbuje włączyć system alarmowy wymagający kodu PIN. System wykrywa, że przednie i tylne okna są otwarte, i wyświetla użytkownikowi prośbę o potwierdzenie włączenia uzbrojenia.
| Użytkownik | Włącz tryb Poza domem. |
| 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 nadal włączać system alarmowy? |
| Użytkownik | Tak. |
| Asystent Google | OK, włączam system alarmowy na zewnątrz |
Na pierwszym etapie odpowiedź powinna stanowić standardowe wyzwanie 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 dotyczące podanego kodu PIN. Aby obsługiwać drugi skręt, odpowiedź na wyzwanie ackNeeded powinna zawierać dodatkowe informacje, w tym docelowy poziom gałęzi i bieżący raport o stanie z wyjątkami.
{
"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 przekazany w pierwszym kroku.
{
"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
}
}
]
}
}