Guide sur 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 armés à plusieurs niveaux de sécurité (par exemple, "Chez moi" et "Absent") et peuvent signaler des informations sur certains capteurs, comme un capteur qui détecte un mouvement ou une fenêtre ouverte.

Ce type indique que l'appareil reçoit l'icône du système de sécurité, ainsi que certains synonymes et alias associés.

Fonctionnalités de l'appareil

Consultez la documentation de la caractéristique correspondante pour obtenir des informations sur l'implémentation, comme les attributs et les états que votre service doit prendre en charge, et sur la façon de créer des réponses EXECUTE et QUERY.

Traits requis

Ces traits et commandes sont obligatoires, le cas échéant, pour votre appareil. Si votre appareil n'est pas compatible avec ces caractéristiques, saisissez le code d'erreur functionNotSupported dans une réponse QUERY ou EXECUTE. Pour en savoir plus, consultez Erreurs et exceptions.

Ces caractéristiques sont recommandées, si elles s'appliquent à votre appareil. Toutefois, vous êtes libre de combiner les traits disponibles pour qu'ils correspondent au mieux aux fonctionnalités de votre produit.

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é" courant, basé sur le type d'appareil et les 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

Demande
{   "requestId": "6894439706274654512",   "inputs": [     {       "intent": "action.devices.SYNC"     }   ] }
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

Demande
{   "requestId": "6894439706274654514",   "inputs": [     {       "intent": "action.devices.QUERY",       "payload": {         "devices": [           {             "id": "123"           }         ]       }     }   ] }
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 la commande, consultez la documentation de référence sur action.devices.traits.ArmDisarm.

Demande
{   "requestId": "6894439706274654516",   "inputs": [     {       "intent": "action.devices.EXECUTE",       "payload": {         "commands": [           {             "devices": [               {                 "id": "123"               }             ],             "execution": [               {                 "command": "action.devices.commands.ArmDisarm",                 "params": {                   "arm": true,                   "armLevel": "away_key"                 }               }             ]           }         ]       }     }   ] }
Réponse
{   "requestId": "6894439706274654516",   "payload": {     "commands": [       {         "ids": [           "123"         ],         "status": "SUCCESS",         "states": {           "online": true,           "isArmed": true,           "currentArmLevel": "away_key"         }       }     ]   } }

ERREURS liées à l'appareil

Consultez la liste complète des erreurs et exceptions.

Signaler des exceptions d'armement

Lorsque vous tentez d'armer ou de désarmer le système, vous pouvez fournir un contexte supplémentaire à l'aide de codes d'exception que vous signalez via le trait StatusReport. Les exceptions peuvent être signalées comme bloquantes ou non bloquantes.

  • Les exceptions non bloquantes signalées avec l'état "SUCCESS" (RÉUSSITE) indiquent que l'exception n'a pas empêché l'activation ou la désactivation.
  • Les exceptions bloquantes signalées avec l'état "EXCEPTIONS" indiquent que l'armement ou le désarmement a été arrêté en raison de ces exceptions.

Voici quelques codes d'exception couramment associés aux systèmes de sécurité :

  • doorOpen : une porte est ouverte.
  • windowOpen : une fenêtre est ouverte.
  • isOpen : un capteur détecte qu'un élément est ouvert (mais ne sait pas s'il s'agit d'une porte ou d'une fenêtre).

Exemple : exception non bloquante

Cet exemple montre une exception non bloquante où le système de sécurité est armé même si une fenêtre est signalée comme ouverte.

Utilisateur Règle le système de sécurité sur un niveau élevé.
Assistant Google OK, la vitre avant est ouverte. J'active le système de sécurité sur un niveau élevé.
Demande
{     "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"             }           }]         }]       }     }]   }
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 de blocage

Utilisateur Règle le système de sécurité sur un niveau élevé.
Assistant Google Une erreur s'est produite lors du contrôle du système de sécurité. La fenêtre de devant est ouverte.
Demande
{     "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"             }           }]         }]       }     }]   }
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"               }             ]           }         }       ]     }   }

Armer le système avec l'authentification à deux facteurs

Si votre flux d'armement exige que les utilisateurs saisissent un code dans une boîte de dialogue d'authentification à deux facteurs, vous devez leur demander s'ils souhaitent continuer à armer le système lorsqu'il existe des exceptions actives (par exemple, lorsqu'une fenêtre ou une porte est ouverte).

Dans ce scénario, vous devrez peut-être à la fois saisir un code ou une phrase secrète, puis confirmer.

Exemple : Défi de confirmation

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

Utilisateur Active 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.

Requête 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             }           }]         }]       }     }]   }
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 requête ultérieure que Google vous enverra contiendra le résultat ack.

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

Exemple : Défi de validation par code et confirmation

Cet exemple montre un utilisateur qui tente d'armer le système de sécurité et doit saisir un code. Le système détecte que les vitres avant et arrière sont ouvertes et demande à l'utilisateur de confirmer que l'armement doit se poursuivre.

Utilisateur Active le mode Absent.
Assistant Google Quel est votre code ?
Utilisateur 1234
Assistant Google Il semble que les vitres avant et arrière soient ouvertes. Voulez-vous vraiment continuer à armer le système de sécurité en mode Absent ?
Utilisateur Oui.
Assistant Google OK, j'active le système de sécurité sur Absence.

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

Requête 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           }         }]       }]     }   }] }
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. Pour prendre en charge le deuxième tour, vous devez répondre avec un défi ackNeeded contenant des informations supplémentaires, y compris le niveau de bras cible et le rapport d'état actuel avec les exceptions de blocage.

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

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