Anleitung für Smart-Home-Sicherheitssysteme

action.devices.types.SECURITYSYSTEM: Sicherheitssysteme können scharf und unscharf geschaltet werden. Sie können auf mehreren Sicherheitsstufen (z. B. „Zuhause“ und „Abwesend“) scharf geschaltet werden und Daten zu bestimmten Sensoren melden, z. B. einem Sensor, der Bewegungen oder ein offenes Fenster erkennt.

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

Gerätefunktionen

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

Erforderliche Merkmale

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

Diese Traits werden empfohlen, sofern sie für Ihr Gerät relevant sind. Sie können jedoch alle verfügbaren Merkmale beliebig kombinieren und so optimal an Ihre vorhandene Produktfunktionalität anpassen.

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 Beispiele für Intent-Nutzlasten, die basierend auf dem obigen Gerätetyp und den oben genannten Merkmalen ein gängiges „Sicherheitssystem“ 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 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"
          }
        ]
      }
    }
  }
}

Beispiele für EXECUTE-Befehle

ArmDisarm

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

Vollständige Liste der Fehler und Ausnahmen

Ausnahmen für die Scharfschaltung melden

Wenn du versuchst, das System scharf oder unscharf zu schalten, kannst du über Ausnahmecodes zusätzlichen Kontext liefern, den du über die Eigenschaft StatusReport meldest. Ausnahmen können als blockierend oder nicht blockierend gemeldet werden.

  • Nicht blockierende Ausnahmen mit dem Status "SUCCESS" geben an, dass die Ausnahme die Aktivierung oder Unscharfschaltung nicht verhindert hat.
  • Ausnahmen vom Typ „Blockieren“ mit dem Status „AUSNAHME“ zeigen an, dass das Scharf- oder Unscharfschalten aufgrund dieser Ausnahmen gestoppt wurde.

Zu den Ausnahmecodes, die häufig mit Sicherheitssystemen in Verbindung gebracht werden, gehören:

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

Beispiel: Nicht blockierende Ausnahme

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

Nutzer Stellen Sie das Sicherheitssystem auf hohe Sicherheit ein.
Google Assistant Okay, das Fenster vorne ist geöffnet. Das Sicherheitssystem wird auf hohe Sicherheit 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 Bei der Steuerung des Sicherheitssystems ist ein Fehler aufgetreten. Das Fenster vorne 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"
              }
            ]
          }
        }
      ]
    }
  }

Mit 2-Faktor-Authentifizierung scharf schalten

Wenn Nutzer beim Scharfschalten eine PIN über ein Dialogfeld für die 2-Faktor-Authentifizierung eingeben müssen, müssen Sie bestätigen, dass das System auch dann weiter scharf geschaltet werden soll, wenn es aktive Ausnahmen gibt (z. B. wenn ein Fenster oder eine Tür geöffnet ist).

Hierfür müssen Sie möglicherweise sowohl eine PIN als auch eine Passphrase und dann eine Bestätigung eingeben.

Beispiel: Bestätigungsaufforderung

In diesem Beispiel versucht ein Nutzer, das Sicherheitssystem scharf zu schalten, aber die Haustür wird als offen erkannt. Der Nutzer bestätigt, dass das Sicherheitssystem trotz offener Eingangstür scharf geschaltet werden sollte.

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

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 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, wie ein Nutzer versucht, das Sicherheitssystem scharf zu schalten, dessen PIN-Eingabe erforderlich ist. Das System erkennt, dass die Fenster vorne und hinten geöffnet sind, und bittet den Nutzer, zu bestätigen, dass die Scharfschaltung fortgesetzt werden soll.

Nutzer Auf „Abwesend“ scharf schalten.
Google Assistant Wie lautet Ihre PIN?
Nutzer 1234.
Google Assistant Vorder- und Rückfenster sind geöffnet. Möchtest du das Sicherheitssystem wirklich auf „Abwesend“ scharf schalten?
Nutzer Ja.
Google Assistant Okay, das Sicherheitssystem wird auf „Abwesend“ geschaltet

In der ersten Runde sollten Sie mit einer standardmäßigen 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 Ihnen dann eine Anfrage mit der angegebenen PIN. Um die zweite Runde zu unterstützen, solltest du mit einer ackNeeded-Aufgabe mit zusätzlichen Informationen antworten, einschließlich der Zielverzweigungsebene und des aktuellen Statusberichts mit blockierenden Ausnahmen.

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 Sie in der ersten Runde erhalten haben.

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