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.

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

Prośba
{
  "requestId": "6894439706274654512",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}
Odpowiedź
{
  "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

Prośba
{
  "requestId": "6894439706274654514",
  "inputs": [
    {
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [
          {
            "id": "123"
          }
        ]
      }
    }
  ]
}
Odpowiedź
{
  "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.

Prośba
{
  "requestId": "6894439706274654516",
  "inputs": [
    {
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [
          {
            "devices": [
              {
                "id": "123"
              }
            ],
            "execution": [
              {
                "command": "action.devices.commands.ArmDisarm",
                "params": {
                  "arm": true,
                  "armLevel": "away_key"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
Odpowiedź
{
  "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.
Prośba
{
  "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"
          }
        }]
      }]
    }
  }]
}
Odpowiedź
{
  "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.
Prośba
{
  "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"
          }
        }]
      }]
    }
  }]
}
Odpowiedź 2
{
  "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.

Prośba 1
{
  "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
          }
        }]
      }]
    }
  }]
}
Odpowiedź 2
{
  "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.

Prośba 2
{
  "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
          }
        }]
      }]
    }
  }]
}
Odpowiedź
{
  "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.

Prośba 1
{
  "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
          }
        }]
      }]
    }
  }]
}
Odpowiedź
{
  "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).

Prośba 2
{
  "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"
          }
        }]
      }]
    }
  }]
}
Odpowiedź
{
  "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.

Prośba 3
{
  "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
          }
        }]
      }]
    }
  }]
}
Odpowiedź
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "isArmed": true
        }
      }
    ]
  }
}