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 du système de sécurité, ainsi que des synonymes et alias associés.
Fonctionnalités de l'appareil
Reportez-vous à la documentation sur les fonctionnalités correspondantes pour obtenir des détails d'implémentation, tels que les attributs et les états que votre service doit prendre en charge, et pour découvrir comment créer des réponses EXECUTE et QUERY.
Caractéristiques requises
Ces caractéristiques et commandes sont obligatoires, le cas échéant. 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. Pour en savoir plus, consultez la section Erreurs et exceptions.
Caractéristiques recommandées
Ces caractéristiques sont recommandées, si elles s'appliquent à votre appareil. Cependant, vous êtes libre de combiner toutes les caractéristiques disponibles pour correspondre au mieux aux fonctionnalités existantes de votre 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
{ "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" } } ] } }
Exemple de réponse QUERY
{ "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" } ] } } } }
Exemples de commandes EXECUTE
ArmDisarm
Pour en savoir plus sur les paramètres de commande, consultez la documentation de référence sur
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" } } ] } }
Erreurs d'appareil
Consultez la liste complète des erreurs et exceptions.Signaler les exceptions d'activation
Lorsque vous tentez d'activer ou de désactiver le système, vous pouvez fournir davantage de contexte via des codes d'exception que vous signalez à l'aide de la caractéristique StatusReport. Les exceptions peuvent être signalées comme bloquantes ou non bloquantes.
- Les exceptions non bloquantes signalées avec l'état "SUCCÈS" indiquent que l'exception n'a pas empêché l'activation ou la désactivation.
- Les exceptions de blocage signalées à l'état "EXCEPTIONS" indiquent que l'activation ou la désactivation a été arrêtée 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 ouverte. J'active le niveau de sécurité élevé du système de sécurité. |
{
"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"
}
]
}
}
]
}
}
Exemple: Exception bloquante
Utilisateur | Définissez le système de sécurité sur "Sécurité élevée". |
Assistant Google | Une erreur s'est produite lors du contrôle du système de sécurité. La fenêtre avant est ouverte. |
{
"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"
}
]
}
}
]
}
}
Activation avec l'authentification à deux facteurs
Si votre flux d'activation exige des utilisateurs qu'ils saisissent un code PIN via une boîte de dialogue d'authentification à deux facteurs, vous devez indiquer s'ils souhaitent continuer à activer le système en cas d'exceptions actives (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 une porte d'entrée est détectée comme étant ouverte. L'utilisateur reconnaît que le système de sécurité 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 | D'accord, j'active le système de sécurité. |
Au premier tour, vous devez répondre avec un défi ackNeeded
.
{
"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"
}
]
}
}
]
}
}
La demande suivante de Google qui vous sera adressée contiendra le résultat 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
}
}
]
}
}
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 de confirmer que l'activation doit se poursuivre.
Utilisateur | Activer le mode Absent. |
Assistant Google | Quel est votre code ? |
Utilisateur | 1234 |
Assistant Google | Il semble que 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, j'active le système de sécurité sur Absent |
Au premier tour, vous devez répondre avec un défi pinNeeded
standard.
{ "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 envoie ensuite une demande contenant le code fourni. Pour faciliter le deuxième tour, vous devez répondre avec un défi ackNeeded
en fournissant des informations supplémentaires, y compris le niveau du bras cible et le rapport d'état actuel avec les exceptions bloquantes.
{ "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" } }] } }
La demande ultérieure de Google ne contiendra que le résultat ack
, et non le code fourni lors du premier tour.
{ "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 } } ] } }