智能家居安全系统指南
action.devices.types.SECURITYSYSTEM
- 安防系统的报警器可以开启和关闭。它们的报警器可以设置为多个安全等级(例如,“在家”和“外出”),也可以报告有关某些传感器的信息,例如用于检测运动或打开的窗户的传感器。
此类型表示设备会获得安全系统图标以及一些相关的同义词和别名。
设备功能
如需了解实现详情(例如您的服务应支持的特性和状态,以及如何构建 EXECUTE 和 QUERY 响应),请参阅相应的特征文档。
必需的特征
这些特征和命令是必需的(如果适用于您的设备)。如果您的设备不支持这些特征,请在 QUERY 或 EXECUTE 响应中输入错误代码 functionNotSupported
。如需了解详情,请参阅错误和异常。
推荐的特征
如果设备适用这些特征,建议提供。 不过,您可以自由组合搭配所有可用特征,以便与现有产品功能实现最佳匹配。
质量要求
- 延迟时间:必须小于或等于 2000 毫秒。
- 可靠性:必须大于或等于 97%。
示例设备:简单的安防系统
本部分包含一些 intent 载荷示例,这些 intent 载荷代表基于上述设备类型和特征的常见“安全系统”。如果您在实现中添加或移除特征,请相应地修改响应以反映这些更改。
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 特征报告的异常代码提供其他上下文。 异常可以报告为阻塞或非阻塞。
- 非阻止异常若被报告为“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": "SUCCESS", "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 } } ] } }