智能家居安全系统指南
action.devices.types.SECURITYSYSTEM - 安防系统的报警器可以开启和关闭。它们的报警器可以设置为多个安全等级（例如，“在家”与“外出”），安防系统还可以报告有关某些传感器的信息，例如用于检测运动或打开的窗户的传感器。
此类型表示设备会获取“安全系统”图标以及一些相关的近义词和别名。
设备功能
如需了解实现详情（例如您的服务应支持的属性和状态，以及如何构建 EXECUTE 和 QUERY 响应），请参阅相应的 trait 文档。
必需的特征
这些 trait 和命令是必需的（如果适用于您的设备）。如果您的设备不支持这些 trait，请在 QUERY 或 EXECUTE 响应中输入 functionNotSupported 错误代码。如需了解详情，请参阅错误和异常。
建议的特征
建议您使用以下 trait（如果适用于您的设备）。 不过，您可以自由组合使用所有可用的 trait，以便尽可能匹配现有的产品功能。
质量要求
- 延迟时间：必须小于或等于 2000 毫秒。
- 可靠性：必须大于或等于 97%。
设备示例：简单的安全系统
本部分包含基于上述设备类型和 trait 的常见“安防系统”intent 载荷示例。如果您在实现中添加或移除 trait，请相应地修改响应以反映这些更改。
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" } } ] } }
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" } ] } } } }
EXECUTE 命令示例
ArmDisarm
如需详细了解命令参数，请参阅
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" } } ] } }
设备错误
查看错误和异常的完整列表。报告上报异常
尝试开启或关闭系统时，您可以通过通过 StatusReport trait 报告的异常代码提供更多背景信息。 异常可以报告为阻塞式或非阻塞式。
- 报告的非阻塞异常如果具有“SUCCESS”状态，则表示该异常未阻止开启或关闭报警器。
- 报告的阻塞异常（状态为“EXCEPTIONS”）表示由于这些异常，系统停止了开启或关闭报警器。
通常与安全系统相关的异常代码包括：
doorOpen：车门未关好。windowOpen：窗口处于打开状态。isOpen：传感器检测到某个东西处于开启状态（但不知道是门还是窗户）。
示例：非阻塞异常
此示例展示了一种非阻塞异常，其中即使窗口被报告为处于打开状态，安防系统也会处于开启状态。
| 用户 | 将安防系统设为高安保等级。 |
| Google 助理 | 好的，前车窗已打开。将安防系统开启，安保等级设为高。 |
{
"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"
}
]
}
}
]
}
}示例：阻塞异常
| 用户 | 将安防系统设为高安保等级。 |
| Google 助理 | 控制安全系统时出错。前窗是开着的。 |
{
"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"
}
]
}
}
]
}
}启用双重身份验证
如果您的布防流程要求用户通过两步验证对话框输入 PIN 码，则必须确认用户是否希望在存在有效例外情况（例如窗户或门处于打开状态）时继续布防系统。
在这种情况下，您可能需要输入 PIN 码或口令，然后进行确认。
示例：确认问题
此示例显示，用户尝试开启安全系统，但系统检测到前门处于打开状态。用户确认，即使前门处于打开状态，安防系统也应处于开启状态。
| 用户 | 开启安防系统报警器。 |
| Google 助理 | 前门是开着的。 确定要开启安全系统吗？ |
| 用户 | 是。 |
| Google 助理 | 好的，正在开启安防系统报警器。 |
在第一回合中，您应使用 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"
}
]
}
}
]
}
}Google 随后向您发出的请求将包含 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
}
}
]
}
}示例：PIN 码和确认质询
此示例展示了用户尝试启用需要输入 PIN 码的安全系统。 系统检测到前后车窗处于打开状态，并要求用户确认是否应继续上锁。
| 用户 | 安保等级设为“远离”。 |
| Google 助理 | 您的 PIN 码是什么？ |
| 用户 | 1234。 |
| Google 助理 | 前窗和后窗似乎是开着的。确定要继续将安全系统设为外出模式吗？ |
| 用户 | 是。 |
| Google 助理 | 好的，将安防系统设为外出模式 |
在第一回合中，您应使用标准 pinNeeded 质询进行回复。
{ "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 会跟进一个包含所提供 PIN 码的请求。为了支持第二轮，您应回复 ackNeeded 质询，并附上其他信息，包括目标平台级别，以及包含屏蔽异常的当前状态报告。
{ "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" } }] } }
Google 随后向您发出的请求将仅包含 ack 结果，而不会包含第一轮提供的 PIN 码。
{ "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 } } ] } }