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 à différents niveaux de sécurité (par exemple, domicile et absence) 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 des synonymes et alias associés.

Fonctionnalités de l'appareil

Reportez-vous à la documentation sur les caractéristiques correspondantes pour obtenir des détails sur l'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.

Traits obligatoires

Ces caractéristiques et commandes sont requises, si applicables à votre appareil. Si votre appareil n'est pas compatible avec ces traits, saisissez le code d'erreur de functionNotSupported dans une réponse QUERY ou EXECUTE. Pour en savoir plus, consultez la section 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 qu'elles correspondent au mieux aux fonctionnalités de votre produit.

Exigences de qualité

  • Latence:doit être inférieure ou égale à 2 000 ms.
  • Fiabilité:la valeur 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 décrites 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 modifications.

Exemple de réponse SYNC

Demander
{
  "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

Demander
{
  "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.

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"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
Réponse
{
  "requestId": "6894439706274654516",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "isArmed": true,
          "currentArmLevel": "away_key"
        }
      }
    ]
  }
}

ERREURS sur l'appareil

Consultez la liste complète des erreurs et exceptions.

Signaler des exceptions d'activation

Lorsque vous tentez d'activer ou de désactiver le système, vous pouvez fournir du contexte supplémentaire via des codes d'exceptions que vous signalez via la caractéristique StatusReport. Les exceptions peuvent être signalées comme étant 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.
  • Les exceptions bloquantes signalées avec l'état "EXCEPTIONS" indiquent que l'activation ou la désactivation a été interrompue en raison de ces exceptions.

Voici les 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 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 dans laquelle le système de sécurité est activé même si une fenêtre est signalée comme ouverte.

Utilisateur Configurez le système de sécurité sur le niveau de sécurité élevé.
Assistant Google OK, la fenêtre avant est ouverte. J'active le système de sécurité à un niveau de sécurité élevé.
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"
          }
        }]
      }]
    }
  }]
}
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 Configurez le système de sécurité sur le niveau de sécurité élevé.
Assistant Google Une erreur s'est produite lors du contrôle du système de sécurité. La fenêtre avant est ouverte.
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"
          }
        }]
      }]
    }
  }]
}
Réponse 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "isArmed": false,
          "currentArmLevel": "L2",
          "currentStatusReport": [
            {
              "blocking": true,
              "priority": 0,
              "statusCode": "windowOpen",
              "deviceTarget": "sensor_id1"
            }
          ]
        }
      }
    ]
  }
}

Activation avec une authentification à deux facteurs

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

Dans ce cas, vous devrez peut-être saisir à la fois un code ou une phrase secrète, suivis d'un accusé de réception.

Exemple: Défi de reconnaissance

Cet exemple montre un utilisateur qui tente d'activer le système de sécurité, mais une porte d'entrée a été détectée comme ouverte. L'utilisateur comprend 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.

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
          }
        }]
      }]
    }
  }]
}
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 que Google vous envoie 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: code et question d'accusé de réception

Cet exemple montre un utilisateur qui tente d'activer le système de sécurité en exigeant la saisie du code PIN. Le système détecte que les vitres avant et arrière sont ouvertes, et demande à l'utilisateur de confirmer que l'activation doit se poursuivre.

Utilisateur Activez le mode Absent.
Assistant Google Quel est votre code PIN ?
Utilisateur 1234.
Assistant Google Il semble que la fenêtre avant et la fenêtre arrière sont ouvertes. Voulez-vous vraiment continuer à activer le système de sécurité sur Absent ?
Utilisateur Oui.
Assistant Google D'accord, j'active le système de sécurité sur Absent

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

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

Google donne ensuite suite à une demande contenant le code fourni. Pour effectuer la deuxième étape, vous devez répondre par un défi ackNeeded avec des informations supplémentaires, y compris le niveau du groupe cible et le rapport d'état actuel avec les exceptions bloquantes.

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 suivante que Google vous envoie ne contiendra que le résultat ack, et non le code fourni au 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
        }
      }
    ]
  }
}