Leitfaden für Smart-Home-Sicherheitssysteme

action.devices.types.SECURITYSYSTEM – Sicherheitssysteme können scharf und unscharf geschaltet werden. Sie können mit mehreren Sicherheitsstufen scharf geschaltet werden (z. B. „Zuhause“ und „Abwesend“) und Informationen zu bestimmten Sensoren senden, z. B. zu einem Sensor, der Bewegungen oder ein geöffnetes Fenster erkennt.

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

Gerätefunktionen

In der entsprechenden Dokumentation zu Merkmalen finden Sie Implementierungsdetails wie Attribute und Status, die Ihr Dienst unterstützen sollte, sowie Informationen zum Erstellen von EXECUTE- und QUERY-Antworten.

Erforderliche Merkmale

Diese Merkmale und Befehle sind erforderlich, sofern sie für Ihr Gerät gelten. Wenn Ihr Gerät diese Eigenschaften nicht unterstützt, geben Sie den Fehlercode functionNotSupported in einer QUERY- oder EXECUTE-Antwort ein. Weitere Informationen finden Sie unter Fehler und Ausnahmen.

Diese Eigenschaften werden empfohlen, sofern sie für Ihr Gerät gelten. Sie können jedoch alle verfügbaren Merkmale kombinieren, um sie bestmöglich an Ihre vorhandenen Produktfunktionen anzupassen.

Qualitätsanforderungen

  • Latenz:muss kleiner als oder gleich 2.000 ms sein.
  • Zuverlässigkeit:muss mindestens 97% betragen.

Beispielgerät: Einfaches Sicherheitssystem

Dieser Abschnitt enthält Beispielnutzlasten für Intents, die ein gängiges „Sicherheitssystem“ basierend auf den oben genannten Gerätetypen und -merkmalen darstellen. Wenn Sie in Ihrer Implementierung Merkmale hinzufügen oder entfernen, ändern Sie Ihre Antworten entsprechend, um diese Änderungen widerzuspiegeln.

Beispiel für eine 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 eine 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"
          }
        ]
      }
    }
  }
}

Beispielbefehle für EXECUTE

ArmDisarm

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

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ÄTEFEHLER

Eine vollständige Liste der Fehler und Ausnahmen

Ausnahmen für die Alarmaktivierung melden

Wenn Sie versuchen, das System zu aktivieren oder zu deaktivieren, können Sie über Ausnahmecodes, die Sie über das Attribut StatusReport melden, zusätzlichen Kontext angeben. Ausnahmen können als blockierend oder nicht blockierend gemeldet werden.

  • Nicht blockierende Ausnahmen mit dem Status „ERFOLG“ geben an, dass die Ausnahme die Alarmanlage nicht daran gehindert hat, scharf- oder unscharfgestellt zu werden.
  • Blockierende Ausnahmen mit dem Status „AUSNAHMEN“ geben an, dass die Alarmanlage aufgrund dieser Ausnahmen nicht scharf- oder unscharf gestellt werden konnte.

Zu den häufig mit Sicherheitssystemen verknüpften Ausnahmecodes gehören:

  • doorOpen: Eine Tür ist geöffnet.
  • 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

In diesem Beispiel wird eine nicht blockierende Ausnahme gezeigt, bei der das Sicherheitssystem scharf geschaltet ist, obwohl ein Fenster als geöffnet gemeldet wird.

Nutzer Stellen Sie das Sicherheitssystem auf „Hohe Sicherheit“ ein.
Google Assistant Ok, das Fenster vorne ist geöffnet. Das Sicherheitssystem wird auf „Hohe Sicherheit“ 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: Blockierungsausnahme

Nutzer Stellen Sie das Sicherheitssystem auf „Hohe Sicherheit“ ein.
Google Assistant Beim Steuern des Sicherheitssystems ist ein Fehler aufgetreten. Die Windschutzscheibe 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": "EXCEPTIONS",
          "states": {
            "online": true,
            "isArmed": false,
            "currentArmLevel": "L2",
            "currentStatusReport": [
              {
                "blocking": true,
                "priority": 0,
                "statusCode": "windowOpen",
                "deviceTarget": "sensor_id1"
              }
            ]
          }
        }
      ]
    }
  }

Alarmanlage mit 2-Faktor-Authentifizierung aktivieren

Wenn Nutzer bei der Alarmanlage eine PIN über ein Dialogfeld für die 2-Faktor-Authentifizierung eingeben müssen, müssen Sie bestätigen, ob sie die Alarmanlage bei aktiven Ausnahmen weiterhin aktivieren möchten, z. B. wenn ein Fenster oder eine Tür geöffnet ist.

In diesem Szenario ist möglicherweise sowohl die Eingabe einer PIN oder Passphrase als auch eine Bestätigung erforderlich.

Beispiel: Bestätigungsaufforderung

In diesem Beispiel versucht ein Nutzer, das Sicherheitssystem zu aktivieren, aber die Haustür wird als geöffnet erkannt. Der Nutzer bestätigt, dass das Sicherheitssystem scharf geschaltet werden soll, auch wenn die Haustür offen ist.

Nutzer Schalten Sie das Sicherheitssystem scharf.
Google Assistant Die Eingangstür ist unverschlossen. Sind Sie sicher, dass Sie das Sicherheitssystem aktivieren möchten?
Nutzer Ja.
Google Assistant Ok, ich schaffe das.

In der ersten Runde sollten Sie mit einer ackNeeded-Herausforderung 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 ack-Ergebnis.

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ätigungsanfrage

In diesem Beispiel versucht ein Nutzer, das Sicherheitssystem zu aktivieren, für das eine PIN eingegeben werden muss. Das System erkennt, dass die vorderen und hinteren Fenster geöffnet sind, und fordert den Nutzer auf, zu bestätigen, dass die Alarmanlage aktiviert werden soll.

Nutzer „Abwesend“ scharf schalten
Google Assistant Wie lautet Ihre PIN?
Nutzer 1234.
Google Assistant Offenbar sind das vordere und das hintere Fenster geöffnet. Sind Sie sicher, dass Sie das Sicherheitssystem weiterhin auf „Abwesend“ stellen möchten?
Nutzer Ja.
Google Assistant Okay, ich schaffe das Sicherheitssystem auf „Abwesend“.

In der ersten Runde sollten Sie mit einer Standard-pinNeeded-Herausforderung 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 dann eine Anfrage mit der angegebenen PIN. Um die zweite Anfrage zu unterstützen, sollten Sie mit einer ackNeeded-Anfrage mit zusätzlichen Informationen antworten, einschließlich der Ebene der Zielverzweigung 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 ack-Ergebnis und nicht die PIN, die in der ersten Runde angegeben wurde.

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
        }
      }
    ]
  }
}