Guide du système 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, "Maison" 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

Pour en savoir plus sur l'implémentation, comme les attributs et les états que votre service doit prendre en charge, ainsi que sur la création de réponses EXECUTE et QUERY, consultez la documentation du trait correspondant.

Traits obligatoires

Ces traits et commandes sont obligatoires, le cas échéant pour votre appareil. Si votre appareil ne prend pas en charge ces traits, saisissez le code d'erreur functionNotSupported dans une réponse QUERY ou EXECUTE. Pour en savoir plus, consultez la section Erreurs et exceptions.

Ces traits sont recommandés, le cas échéant pour votre appareil. Toutefois, vous êtes libre de combiner tous les traits disponibles pour qu'ils correspondent au mieux aux fonctionnalités de votre produit existant.

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 traits ci-dessus. Si vous ajoutez ou supprimez des traits 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 action.devices.traits.ArmDisarm documentation de référence.

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 de l'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 un contexte supplémentaire via des 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" indiquent que l'exception n'a pas empêché l'activation ou la désactivation.
  • Exceptions bloquantes signalées avec 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 couramment associés aux systèmes de sécurité incluent 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 montre une exception non bloquante où le système de sécurité est activé 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 fenêtre 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 bloquante

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

Activation avec l'authentification à deux facteurs

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

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

Exemple : défi d'accusé de réception

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 activé 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 suivante de Google contiendra le résultat ack.

Requête 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 code secret et d'accusé de réception

Cet exemple montre un utilisateur qui tente d'activer le système de sécurité nécessitant la saisie d'un code secret. 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 Active le mode Absent.
Assistant Google Quel est votre code secret ?
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é en mode Absent ?
Utilisateur Oui.
Assistant Google OK, j'active le système de sécurité en mode Absent.

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 requête contenant le code secret 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 d'activation cible et le rapport d'état actuel avec les exceptions bloquantes.

Requête 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 requête suivante de Google ne contiendra que le ack résultat, et non le code secret fourni au premier tour.

Requête 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
        }
      }
    ]
  }
}