Leitfaden für Smart-Home-Sicherheitssysteme

action.devices.types.SECURITYSYSTEM – Sicherheitssysteme können scharf oder unscharf geschaltet werden. Sie können auf verschiedenen Sicherheitsstufen scharf geschaltet werden (z. B. zu Hause und abwesend) und können Informationen über bestimmte Sensoren senden, z. B. einen Sensor, der eine Bewegung oder ein offenes Fenster erkennt.

Dieser Typ gibt an, dass das Gerät das Sicherheitssystemsymbol und einige zugehörige Synonyme und Aliasse erhält.

Gerätefunktionen

Informationen zur Implementierung finden Sie in der entsprechenden Trait-Dokumentation, z. B. zu Attributen und Statusangaben, die Ihr Dienst unterstützen sollte, und zum Erstellen von EXECUTE- und QUERY-Antworten.

Erforderliche Merkmale

Diese Merkmale und Befehle sind bei Bedarf für Ihr Gerät erforderlich. Wenn dein Gerät diese Traits nicht unterstützt, gib den Fehlercode functionNotSupported in einer QUERY- oder EXECUTE-Antwort ein. Weitere Informationen finden Sie unter Fehler und Ausnahmen.

Diese Traits werden empfohlen, sofern für Ihr Gerät zutreffend. Sie können jedoch alle verfügbaren Merkmale beliebig kombinieren, um der vorhandenen Produktfunktionalität am besten zu entsprechen.

Qualitätsanforderungen

  • Latenz:muss kleiner oder gleich 2.000 ms sein.
  • Zuverlässigkeit: muss größer oder gleich 97% sein.

Beispielgerät: Einfaches Sicherheitssystem

Dieser Abschnitt enthält Beispielnutzlasten für Intents, die ein gemeinsames „Sicherheitssystem“ basierend auf dem oben genannten Gerätetyp und den obigen Merkmalen darstellen. Wenn Sie in Ihrer Implementierung Traits hinzufügen oder entfernen, passen Sie Ihre Antworten entsprechend an.

Beispiel für SYNC-Antwort

Anfrage
{
  "requestId": "6894439706274654512",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}
Antwort
{
  "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"
        }
      }
    ]
  }
}

Beispiel für QUERY-Antwort

Anfrage
{
  "requestId": "6894439706274654514",
  "inputs": [
    {
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [
          {
            "id": "123"
          }
        ]
      }
    }
  ]
}
Antwort
{
  "requestId": "6894439706274654514",
  "payload": {
    "devices": {
      "123": {
        "status": "SUCCESS",
        "online": true,
        "isArmed": true,
        "currentArmLevel": "home_key",
        "currentStatusReport": [
          {
            "blocking": false,
            "deviceTarget": "123",
            "priority": 0,
            "statusCode": "lowBattery"
          }
        ]
      }
    }
  }
}

Beispiele für EXECUTE-Befehle

Scharf schalten

Weitere Informationen zu den Befehlsparametern finden Sie in der Referenz zu action.devices.traits.ArmDisarm.

Anfrage
{
  "requestId": "6894439706274654516",
  "inputs": [
    {
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [
          {
            "devices": [
              {
                "id": "123"
              }
            ],
            "execution": [
              {
                "command": "action.devices.commands.ArmDisarm",
                "params": {
                  "arm": true,
                  "armLevel": "away_key"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
Antwort
{
  "requestId": "6894439706274654516",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "isArmed": true,
          "currentArmLevel": "away_key"
        }
      }
    ]
  }
}

Gerät ERRORS

Sehen Sie sich die vollständige Liste der Fehler und Ausnahmen an.

Ausnahmen für die Scharfschaltung melden

Wenn Sie versuchen, das System scharf oder unscharf zu schalten, können Sie über Ausnahmecodes, die Sie über die Trait StatusReport melden, zusätzlichen Kontext bereitstellen. Ausnahmen können als blockierend oder nicht blockierend gemeldet werden.

  • Nicht blockierende Ausnahmen, die mit dem Status „SUCCESS“ gemeldet werden, geben an, dass die Ausnahme das Scharf- oder Unscharfschalten nicht verhindert hat.
  • Blockieren von Ausnahmen, die mit dem Status „EXCEPTIONS“ gemeldet werden, geben an, dass das Scharf- oder Unscharfschalten aufgrund dieser Ausnahmen gestoppt wurde.

Zu den häufig mit Sicherheitssystemen verbundenen Ausnahmecodes gehören:

  • doorOpen: Eine Tür ist offen.
  • windowOpen: Ein Fenster ist geöffnet.
  • isOpen: Ein Sensor erkennt, dass etwas geöffnet ist, weiß aber nicht, ob es sich um eine Tür oder ein Fenster handelt.

Beispiel: nicht blockierende Ausnahme

Dieses Beispiel zeigt eine nicht blockierende Ausnahme, bei der das Sicherheitssystem scharf geschaltet ist, obwohl ein Fenster als offen gemeldet wurde.

Nutzer Stellen Sie das Sicherheitssystem auf hohe Sicherheit ein.
Google Assistant Ok, das Fenster vorne ist offen. Das Sicherheitssystem wird scharf geschaltet.
Anfrage
{
  "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"
          }
        }]
      }]
    }
  }]
}
Antwort
{
  "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"
            }
          ]
        }
      }
    ]
  }
}

Beispiel: Ausnahme blockieren

Nutzer Stellen Sie das Sicherheitssystem auf hohe Sicherheit ein.
Google Assistant Beim Steuern des Sicherheitssystems ist ein Fehler aufgetreten. Das Fenster ist offen.
Anfrage
{
  "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"
          }
        }]
      }]
    }
  }]
}
Antwort 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"
            }
          ]
        }
      }
    ]
  }
}

Zwei-Faktor-Authentifizierung aktivieren

Wenn Nutzer beim Scharfschalten eine PIN über ein Dialogfeld für die 2-Faktor-Authentifizierung eingeben müssen, musst du bestätigen, dass sie das System weiterhin scharf schalten möchten, wenn es aktive Ausnahmen gibt (z. B. wenn ein Fenster oder eine Tür geöffnet ist).

In diesem Fall ist möglicherweise die Eingabe sowohl als auch eine Passphrase gefolgt von einer Bestätigung erforderlich.

Beispiel: Bestätigungsherausforderung

Dieses Beispiel zeigt einen Nutzer, der versucht, das Sicherheitssystem scharf zu schalten, aber eine Haustür wird als offen erkannt. Der Nutzer bestätigt, dass das Sicherheitssystem scharf geschaltet sein soll, obwohl die Haustür geöffnet ist.

Nutzer Schalte das Sicherheitssystem scharf.
Google Assistant Die Eingangstür ist unverschlossen. Möchten Sie das Sicherheitssystem wirklich scharf schalten?
Nutzer Ja.
Google Assistant Ok, das Sicherheitssystem wird scharf geschaltet.

In der ersten Runde sollten Sie mit einer ackNeeded-Aufgabe antworten.

Anfrage 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
          }
        }]
      }]
    }
  }]
}
Antwort 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"
            }
          ]
        }
      }
    ]
  }
}

Die nachfolgende Anfrage von Google an Sie enthält das Ergebnis ack.

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

Beispiel: PIN und Bestätigungsaufforderung

Dieses Beispiel zeigt einen Nutzer, der versucht, das Sicherheitssystem scharf zu schalten, für das eine PIN-Eingabe erforderlich ist. Das System erkennt, dass die Fenster vorne und hinten geöffnet sind, und fordert den Nutzer auf, zu bestätigen, dass die Scharfschaltung fortgesetzt werden soll.

Nutzer Scharf schalten auf weg.
Google Assistant Wie lautet Ihre PIN?
Nutzer 1234.
Google Assistant Anscheinend sind die Vorder- und die Heckscheibe offen. Möchten Sie das Sicherheitssystem wirklich auf „Abwesend“ scharf schalten?
Nutzer Ja.
Google Assistant Ok, das Sicherheitssystem wird scharf geschaltet

In der ersten Runde sollten Sie mit einer standardmäßigen pinNeeded-Aufgabe antworten.

Anfrage 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
          }
        }]
      }]
    }
  }]
}
Antwort
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["456"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Google sendet daraufhin eine Anfrage mit der angegebenen PIN. Um die zweite Abzweigung zu unterstützen, sollten Sie mit der ackNeeded-Aufgabe mit zusätzlichen Informationen antworten, einschließlich der Zielverzweigungsebene und des aktuellen Statusberichts mit Blockierungsausnahmen.

Anfrage 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"
          }
        }]
      }]
    }
  }]
}
Antwort
{
  "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"
      }
    }]
  }
}

Die nachfolgende Anfrage von Google an Sie enthält nur das Ergebnis ack und nicht die in der ersten Runde angegebene PIN.

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