Leitfaden für Smart-Home-Sicherheitssysteme

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

Dieser Typ gibt an, dass das Gerät das Symbol für das Sicherheitssystem und einige zugehörige Synonyme und Aliase erhält.

Gerätefunktionen

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

Erforderliche Merkmale

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

Diese Merkmale werden empfohlen, sofern sie für Ihr Gerät zutreffen. Sie können jedoch alle verfügbaren Eigenschaften kombinieren, um die vorhandene Produktfunktionalität optimal abzubilden.

Beispielgerät: Einfaches Sicherheitssystem

Dieser Abschnitt enthält Beispielnutzlasten für Intents, die ein gängiges „Sicherheitssystem“ basierend auf dem Gerätetyp und den oben genannten Attributen darstellen. Wenn Sie Ihrer Implementierung Attribute hinzufügen oder daraus entfernen, müssen Sie Ihre Antworten entsprechend anpassen.

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

Beispiel 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 Aktivierung melden

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

  • Nicht blockierende Ausnahmen mit dem Status „SUCCESS“ (ERFOLGREICH) geben an, dass die Ausnahme das Scharf- oder Unscharfschalten nicht verhindert hat.
  • Blockierende Ausnahmen mit dem Status „EXCEPTIONS“ (AUSNAHMEN) weisen darauf hin, dass das Scharf- oder Unscharfschalten aufgrund dieser Ausnahmen beendet wurde.

Häufig mit Sicherheitssystemen verknüpfte Ausnahmecodes:

  • 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

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 offen. 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 geöffnet.
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"
              }
            ]
          }
        }
      ]
    }
  }

Aktivieren des Sicherheitsmodus mit 2‑Faktor-Authentifizierung

Wenn Nutzer in Ihrem Scharfschaltungsablauf eine PIN über ein Dialogfeld für die 2‑Faktor-Authentifizierung eingeben müssen, müssen Sie bestätigen, ob sie das System trotz aktiver Ausnahmen scharfschalten möchten (z. B. wenn ein Fenster oder eine Tür geöffnet ist).

In diesem Fall ist sowohl die Eingabe einer PIN oder eines Sicherheitscodes als auch eine Bestätigung erforderlich.

Beispiel: Bestätigungs-Challenge

In diesem Beispiel versucht ein Nutzer, das Sicherheitssystem zu aktivieren, aber es wird erkannt, dass die Haustür offen ist. Der Nutzer bestätigt, dass das Sicherheitssystem scharf geschaltet werden soll, obwohl die Haustür offen ist.

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

Im ersten Zug sollten Sie mit einer ackNeeded-Aufforderung 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ätigungsaufforderung

In diesem Beispiel versucht ein Nutzer, das Sicherheitssystem zu aktivieren, wozu eine PIN-Eingabe erforderlich ist. Das System erkennt, dass die vorderen und hinteren Fenster geöffnet sind, und fordert den Nutzer auf, zu bestätigen, dass die Aktivierung fortgesetzt werden soll.

Nutzer Schalte auf „Abwesend“ scharf.
Google Assistant Wie lautet Ihre PIN?
Nutzer 1234.
Google Assistant Das Front- und das Heckfenster sind offen. Möchten Sie das Sicherheitssystem wirklich auf „Abwesend“ stellen?
Nutzer Ja.
Google Assistant Okay, das Sicherheitssystem wird auf „Abwesend“ scharf geschaltet.

Im ersten Zug sollten Sie mit einer Standard-pinNeeded-Aufforderung 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 den zweiten Zug zu unterstützen, sollten Sie mit einer ackNeeded-Aufforderung mit zusätzlichen Informationen antworten, einschließlich des Ziel-Arm-Levels 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 im ersten Schritt 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
        }
      }
    ]
  }
}