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.
Empfohlene Eigenschaften
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
{ "requestId": "6894439706274654512", "inputs": [ { "intent": "action.devices.SYNC" } ] }
{ "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
{ "requestId": "6894439706274654514", "inputs": [ { "intent": "action.devices.QUERY", "payload": { "devices": [ { "id": "123" } ] } } ] }
{ "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
.
{ "requestId": "6894439706274654516", "inputs": [ { "intent": "action.devices.EXECUTE", "payload": { "commands": [ { "devices": [ { "id": "123" } ], "execution": [ { "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "away_key" } } ] } ] } } ] }
{ "requestId": "6894439706274654516", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "online": true, "isArmed": true, "currentArmLevel": "away_key" } } ] } }
Gerätefehler
Vollständige Liste der Fehler und AusnahmenAusnahmen 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. |
{
"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"
}
}]
}]
}
}]
}
{
"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. |
{
"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"
}
}]
}]
}
}]
}
{
"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.
{
"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
}
}]
}]
}
}]
}
{
"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
.
{
"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
}
}]
}]
}
}]
}
{
"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.
{ "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 } }] }] } }] }
{ "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.
{ "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" } }] }] } }] }
{ "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.
{ "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 } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "isArmed": true } } ] } }