Guide pour les systèmes de sécurité pour la maison connectée

action.devices.types.SECURITYSYSTEM : les systèmes de sécurité peuvent être activés et désactivés. Ils peuvent être activés à plusieurs niveaux de sécurité (par exemple, chez vous et absent) et ils peuvent transmettre des informations sur certains capteurs, tels qu'un capteur qui détecte un mouvement ou une fenêtre ouverte.

Ce type indique que l'appareil obtient l'icône Système de sécurité et d'autres des synonymes et des alias.

Fonctionnalités de l'appareil

Reportez-vous à la documentation des caractéristiques correspondantes pour les détails de mise en œuvre, tels que les attributs et les états que votre service doit prendre en charge, et comment créer des réponses EXECUTE et QUERY.

Caractéristiques requises

Ces caractéristiques et commandes sont nécessaires, s'il s'agit appareil. Si votre appareil ne prend pas en charge ces caractéristiques, saisissez le code d'erreur de functionNotSupported dans une réponse QUERY ou EXECUTE. Voir Erreurs et exceptions.

Ces caractéristiques sont recommandées, si elles s'appliquent à votre appareil. Cependant, vous êtes libre de combiner toutes les caractéristiques disponibles pour les faire correspondre au mieux la fonctionnalité du produit.

Exigences de qualité

  • Latence:la latence doit être inférieure ou égale à 2 000 ms.
  • La fiabilité doit être supérieure ou égale à 97%.

Exemple d'appareil: système de sécurité simple

Cette section contient des exemples de charges utiles d'intent représentant un "système de sécurité" commun en fonction du type d'appareil et des caractéristiques ci-dessus. Si vous ajoutez ou supprimez des caractéristiques dans votre implémentation, modifiez vos réponses en conséquence pour refléter ces changements.

Exemple de réponse SYNC

<ph type="x-smartling-placeholder">
</ph>
Demander
{
  "requestId": "6894439706274654512",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}
<ph type="x-smartling-placeholder">
</ph>
Réponse
{
  "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"
        }
      }
    ]
  }
}

Exemple de réponse QUERY

<ph type="x-smartling-placeholder">
</ph>
Demander
{
  "requestId": "6894439706274654514",
  "inputs": [
    {
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [
          {
            "id": "123"
          }
        ]
      }
    }
  ]
}
<ph type="x-smartling-placeholder">
</ph>
Réponse
{
  "requestId": "6894439706274654514",
  "payload": {
    "devices": {
      "123": {
        "status": "SUCCESS",
        "online": true,
        "isArmed": true,
        "currentArmLevel": "home_key",
        "currentStatusReport": [
          {
            "blocking": false,
            "deviceTarget": "123",
            "priority": 0,
            "statusCode": "lowBattery"
          }
        ]
      }
    }
  }
}

Exemples de commandes EXECUTE

ArmDisarm

Pour en savoir plus sur les paramètres de commande, consultez les action.devices.traits.ArmDisarm référence.

<ph type="x-smartling-placeholder">
</ph>
Demander
{
  "requestId": "6894439706274654516",
  "inputs": [
    {
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [
          {
            "devices": [
              {
                "id": "123"
              }
            ],
            "execution": [
              {
                "command": "action.devices.commands.ArmDisarm",
                "params": {
                  "arm": true,
                  "armLevel": "away_key"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
<ph type="x-smartling-placeholder">
</ph>
Réponse
{
  "requestId": "6894439706274654516",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "isArmed": true,
          "currentArmLevel": "away_key"
        }
      }
    ]
  }
}

Erreurs d'appareil

Voir la liste complète les erreurs et les exceptions.

Signaler les exceptions d'activation

Lorsque vous essayez d'activer ou de désactiver le système, vous pouvez fournir des le contexte via des codes d'exception. que vous signalez via la caractéristique StatusReport. Les exceptions peuvent être signalées comme bloquantes ou non bloquantes.

  • Les exceptions non bloquantes sont signalées avec le message "SUCCÈS". indiquent que l'exception n'a pas empêché l'activation ou la désactivation.
  • Les exceptions de blocage signalées avec le message "EXCEPTIONS" indiquent que l'activation ou la désactivation ont été arrêtées en raison de ces exceptions.

Les codes d'exception souvent associés aux systèmes de sécurité sont les suivants:

  • doorOpen: une porte est ouverte.
  • windowOpen: une fenêtre est ouverte.
  • isOpen: un capteur détecte que quelque chose est ouvert, mais ne sait pas s'il s'agit d'une porte ou d'une fenêtre).

Exemple: Exception non bloquante

Cet exemple présente une exception non bloquante dans laquelle le système de sécurité est activé même si une fenêtre est signalée comme ouverte.

Utilisateur Définissez le système de sécurité sur "Sécurité élevée".
Assistant Google OK, la fenêtre avant est ouvert. J'active le niveau de sécurité élevé du système de sécurité.
<ph type="x-smartling-placeholder">
</ph>
Demander
{
    "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"
            }
          }]
        }]
      }
    }]
  }
<ph type="x-smartling-placeholder">
</ph>
Réponse
{
    "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"
              }
            ]
          }
        }
      ]
    }
  }

Exemple: Exception bloquante

Utilisateur Définissez le système de sécurité sur "Sécurité élevée".
Assistant Google Une erreur s'est produite. du contrôle du système de sécurité. La fenêtre avant est ouverte.
<ph type="x-smartling-placeholder">
</ph>
Demander
{
    "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"
            }
          }]
        }]
      }
    }]
  }
<ph type="x-smartling-placeholder">
</ph>
Réponse 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"
              }
            ]
          }
        }
      ]
    }
  }

Activation avec l'authentification à deux facteurs

Si votre flux d'activation exige que les utilisateurs saisissent un code PIN via un d'authentification à deux facteurs, vous devez confirmer s'il souhaite continuer à activer le système des exceptions (par exemple, lorsqu'une fenêtre ou une porte est ouverte).

Ce scénario peut nécessiter la saisie à la fois d'un code ou d'une phrase secrète, puis d'un accusé de réception.

Exemple: Test de confirmation

Dans cet exemple, un utilisateur tente d'activer le système de sécurité, mais la porte d'entrée est détectée comme ouverte. L'utilisateur reconnaît que la sécurité système doit être activé même si la porte d'entrée est ouverte.

Utilisateur Activez le système de sécurité.
Assistant Google La porte d'entrée est ouverte. Voulez-vous vraiment activer le système de sécurité ?
Utilisateur Oui.
Assistant Google OK, j'active le système de sécurité.

Au premier tour, vous devez répondre avec un défi ackNeeded.

<ph type="x-smartling-placeholder">
</ph>
Demande 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
            }
          }]
        }]
      }
    }]
  }
<ph type="x-smartling-placeholder">
</ph>
Réponse 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"
              }
            ]
          }
        }
      ]
    }
  }

La demande suivante de Google qui vous sera adressée contiendra le résultat ack.

<ph type="x-smartling-placeholder">
</ph>
Demande 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
            }
          }]
        }]
      }
    }]
  }
<ph type="x-smartling-placeholder">
</ph>
Réponse
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "SUCCESS",
          "states": {
            "isArmed": true
          }
        }
      ]
    }
  }

Exemple: question d'authentification via un code ou une confirmation

Dans cet exemple, un utilisateur tente d'activer un système de sécurité nécessitant la saisie d'un code. Le système détecte que les fenêtres avant et arrière sont ouvertes et demande à l'utilisateur d'en confirmer que l'activation doit se poursuivre.

Utilisateur Activer le mode Absent.
Assistant Google Quel est votre code ?
Utilisateur 1234
Assistant Google Il semble les fenêtres avant et arrière sont ouvertes. Voulez-vous vraiment continuer ? activer le système de sécurité sur Absent ?
Utilisateur Oui.
Assistant Google OK, activer système de sécurité sur "Absent"

Au premier tour, vous devez répondre avec un défi pinNeeded standard.

<ph type="x-smartling-placeholder">
</ph>
Demande 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
          }
        }]
      }]
    }
  }]
}
<ph type="x-smartling-placeholder">
</ph>
Réponse
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["456"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Google envoie ensuite une demande contenant le code fourni. Afin de soutenir au deuxième tour, vous devez répondre avec un défi ackNeeded avec des informations supplémentaires, y compris le niveau de groupe cible et le rapport d’état actuel avec des exceptions bloquantes.

<ph type="x-smartling-placeholder">
</ph>
Demande 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"
          }
        }]
      }]
    }
  }]
}
<ph type="x-smartling-placeholder">
</ph>
Réponse
{
  "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"
      }
    }]
  }
}

La demande ultérieure de Google ne contiendra que le résultat ack, et non le code fourni lors du premier tour.

<ph type="x-smartling-placeholder">
</ph>
Demande 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
          }
        }]
      }]
    }
  }]
}
<ph type="x-smartling-placeholder">
</ph>
Réponse
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "isArmed": true
        }
      }
    ]
  }
}