智慧型住宅安全系統指南
action.devices.types.SECURITYSYSTEM
- 保全系統可以啟動及解除。這類裝置可在多種安全等級 (例如住家和外出) 啟動,並且回報特定感應器的相關資訊,例如感應器偵測到動作的感應器或已開啟窗戶的感應器。
這個類型表示裝置會取得安全系統圖示和一些相關的同義詞和別名。
裝置功能
請參閱對應的特徵說明文件,瞭解實作詳情,例如瞭解服務支援的屬性和狀態,以及如何建構 EXECUTE 和 QUERY 回應。
必要特徵
您需要這些 traits 和指令 (如果裝置適用的話)。如果您的裝置不支援這些特徵,請在 QUERY 或 EXECUTE 回應中輸入 functionNotSupported
的錯誤代碼。詳情請參閱「錯誤與例外狀況」一節。
推薦 traits
建議使用這些 traits (適用於您的裝置)。不過,您可以自由混用所有可用特徵,以最符合現有產品功能的需求。
品質規定
- 延遲時間:必須小於或等於 2000 毫秒。
- 可靠性:必須大於或等於 97%。
裝置範例:簡易的安全系統
本節包含代表上述裝置類型和特徵的意圖酬載範例,如果您在實作中新增或移除特徵,請根據變更來修改回應。
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 特徵回報的例外狀況代碼提供其他背景資訊。例外狀況可能為封鎖或非阻塞式。
- 非封鎖例外狀況若處於「成功」狀態,表示例外狀況並未阻止啟動或解除。
- 回報的封鎖例外狀況狀態為「EXCEPTIONS」代表因上述例外狀況而已停止啟動或解除。
常見的安全系統例外狀況代碼包括:
doorOpen
:門打開了。windowOpen
:視窗已開啟。isOpen
:感應器偵測到未開啟的東西 (但不知道是門還是窗口)。
示例:非封鎖例外狀況
此範例是非阻塞的例外狀況,也就是安全系統雖然回報為開啟狀態,但保全系統已啟動。
User | 將保全系統設為高安全性模式。 |
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" } ] } } ] } }
範例:封鎖例外狀況
User | 將保全系統設為高安全性模式。 |
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 碼或通關密語,才能接著進行確認。
範例:確認驗證問題
這個範例顯示使用者嘗試啟動保全系統,但系統偵測到前門為開著。使用者瞭解即使前門已開啟,保全系統應啟動。
User | 啟動保全系統。 |
Google 助理 | 前門打開了。 確定要啟動保全系統嗎? |
User | 可以。 |
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 碼的保全系統。系統會偵測前座與返回視窗已開啟,並要求使用者確認應繼續執行啟動作業。
User | 啟動遠方。 |
Google 助理 | 你的 PIN 碼為何? |
User | 1234. |
Google 助理 | 看來前窗和後窗是開著的。確定要繼續啟動保全系統嗎? |
User | 可以。 |
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 } } ] } }