Panduan Sistem Keamanan Smart Home
action.devices.types.SECURITYSYSTEM
- Sistem keamanan dapat diaktifkan dan dinonaktifkan. Alarm dapat diaktifkan di beberapa tingkat keamanan (misalnya, di rumah dan pergi) dan dapat melaporkan informasi tentang sensor tertentu, seperti sensor yang mendeteksi gerakan atau jendela yang terbuka.
Jenis ini menunjukkan bahwa perangkat mendapatkan ikon Sistem Keamanan dan beberapa sinonim dan alias terkait.
Kemampuan perangkat
Lihat dokumentasi karakteristik yang sesuai untuk mengetahui detail penerapan, seperti atribut dan status yang harus didukung layanan Anda, serta cara mem-build respons EXECUTE dan QUERY.
Sifat yang diperlukan
Ciri dan perintah ini diperlukan, jika berlaku untuk
perangkat Anda. Jika perangkat Anda tidak mendukung karakteristik ini, masukkan kode error
functionNotSupported
dalam respons QUERY atau EXECUTE. Lihat
Error dan pengecualian untuk mengetahui info selengkapnya.
Karakteristik yang direkomendasikan
Karakteristik ini direkomendasikan, jika berlaku untuk perangkat Anda. Namun, Anda bebas menggabungkan dan mencocokkan dari semua karakteristik yang tersedia agar sesuai dengan fungsi produk yang ada.
Persyaratan kualitas
- Latensi: harus kurang dari atau sama dengan 2.000 md.
- Keandalan: harus lebih besar dari atau sama dengan 97%.
Contoh perangkat: Sistem keamanan sederhana
Bagian ini berisi contoh payload intent yang mewakili "Sistem Keamanan" umum berdasarkan jenis dan karakteristik perangkat di atas. Jika Anda menambahkan atau menghapus karakteristik dalam penerapan, ubah respons Anda agar sesuai dengan perubahan tersebut.
Contoh respons 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" } } ] } }
Contoh respons 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" } ] } } } }
Contoh perintah EXECUTE
ArmDisarm
Untuk detail tambahan tentang parameter perintah,
lihat referensi
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" } } ] } }
ERROR Perangkat
Lihat daftar lengkap error dan pengecualian.Melaporkan pengecualian pengaktifan
Saat mencoba mengaktifkan atau menonaktifkan sistem, Anda dapat memberikan konteks tambahan melalui kode pengecualian yang Anda laporkan melalui karakteristik StatusReport. Pengecualian dapat dilaporkan sebagai memblokir atau tidak memblokir.
- Pengecualian non-pemblokiran yang dilaporkan dengan status "BERHASIL" menunjukkan bahwa pengecualian tidak mencegah pengaktifan atau penonaktifan.
- Pengecualian pemblokiran yang dilaporkan dengan status "EXCEPTIONS" menunjukkan bahwa pengaktifan atau penonaktifan dihentikan karena pengecualian ini.
Kode pengecualian yang biasanya dikaitkan dengan sistem keamanan meliputi:
doorOpen
: Pintu terbuka.windowOpen
: Jendela terbuka.isOpen
: Sensor mendeteksi sesuatu terbuka (tetapi tidak tahu apakah itu pintu atau jendela).
Contoh: Pengecualian non-pemblokiran
Contoh ini menunjukkan pengecualian non-pemblokiran saat sistem keamanan diaktifkan meskipun jendela dilaporkan sebagai terbuka.
Pengguna | Setel sistem keamanan ke tingkat keamanan tinggi. |
Asisten Google | Oke, jendela depan terbuka. Mengaktifkan sistem keamanan ke tingkat keamanan tinggi. |
{
"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"
}
]
}
}
]
}
}
Contoh: Pengecualian pemblokiran
Pengguna | Setel sistem keamanan ke tingkat keamanan tinggi. |
Asisten Google | Terjadi error saat mengontrol sistem keamanan. Jendela depan terbuka. |
{
"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"
}
]
}
}
]
}
}
Mengaktifkan dengan autentikasi 2 langkah
Jika alur pengaktifan Anda mengharuskan pengguna memasukkan PIN melalui dialog autentikasi ganda, Anda harus mengonfirmasi apakah mereka ingin terus mengaktifkan sistem saat ada pengecualian aktif (misalnya, saat jendela atau pintu terbuka).
Skenario ini mungkin memerlukan baik entri PIN atau frasa sandi, diikuti dengan konfirmasi.
Contoh: Tantangan konfirmasi
Contoh ini menunjukkan pengguna yang mencoba mengaktifkan sistem keamanan, tetapi pintu depan terdeteksi terbuka. Pengguna mengonfirmasi bahwa sistem keamanan harus diaktifkan meskipun pintu depan terbuka.
Pengguna | Aktifkan sistem keamanan. |
Asisten Google | Pintu depan terbuka. Yakin ingin mengaktifkan sistem keamanan? |
Pengguna | Ya. |
Asisten Google | Oke, mengaktifkan sistem keamanan. |
Pada giliran pertama, Anda harus merespons dengan tantangan 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"
}
]
}
}
]
}
}
Permintaan berikutnya dari Google kepada Anda akan berisi hasil 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
}
}
]
}
}
Contoh: Tantangan PIN dan konfirmasi
Contoh ini menunjukkan pengguna yang mencoba mengaktifkan sistem keamanan yang memerlukan input PIN. Sistem mendeteksi bahwa jendela depan dan belakang terbuka dan meminta pengguna untuk mengonfirmasi bahwa pengaktifan harus dilanjutkan.
Pengguna | Aktifkan ke mode pergi. |
Asisten Google | Apa PIN Anda? |
Pengguna | 1234. |
Asisten Google | Sepertinya jendela depan dan jendela belakang terbuka. Yakin ingin terus mengaktifkan sistem keamanan ke mode pergi? |
Pengguna | Ya. |
Asisten Google | Oke, mengaktifkan sistem keamanan ke mode pergi |
Pada giliran pertama, Anda harus merespons dengan tantangan pinNeeded
standar.
{ "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" } }] } }
Kemudian, Google akan menindaklanjuti dengan permintaan yang berisi PIN yang diberikan. Untuk mendukung
giliran kedua, Anda harus merespons dengan tantangan ackNeeded
dengan
informasi tambahan, termasuk tingkat lengan target, dan laporan status saat ini dengan
pengecualian pemblokiran.
{ "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" } }] } }
Permintaan berikutnya dari Google kepada Anda hanya akan berisi hasil ack
,
dan bukan PIN yang diberikan pada giliran pertama.
{ "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 } } ] } }