1. Sebelum memulai
Matter menawarkan pengalaman kontrol dan penyiapan perangkat lintas platform yang lancar bagi pengguna akhir. Hal ini terutama dapat dilakukan karena adanya beberapa komponen ekosistem yang bekerja sama di balik layar. Sistem pemecahan masalah seperti ini sering kali menyulitkan developer baru, sehingga kami mengembangkan serangkaian alat dan teknik untuk mempermudah pekerjaan Anda sebagai developer Matter dengan Google Home.
Ada tiga komponen utama untuk Matter yang dibahas dalam codelab ini. Untuk setiap sistem ini, Google memberikan serangkaian analisis pemecahan masalah untuk developer yang dikumpulkan dari ponsel dan hub:
Sebagai developer, Anda harus dapat mengurangi masalah yang Anda alami di sepanjang siklus pengembangan perangkat. Setelah meluncurkan project, Anda perlu memantau tren masalah untuk perangkat di lapangan secara agregat, dan memperbaikinya melalui update software. Codelab ini membahas teknik yang dapat Anda gunakan untuk kedua tujuan tersebut.
Prasyarat
- Selesaikan panduan Memulai Matter dengan penyiapan perangkat dan project Matter yang berfungsi
- Memiliki ponsel Android yang dapat dihubungkan ke workstation (untuk log ADB)
Yang akan Anda pelajari
- Cara menggunakan alat analisis untuk Smart Home guna memantau masalah Matter dalam skala besar.
- Cara memilah kesalahan dengan mengakses log kesalahan dan mengumpulkan informasi.
- Cara mengakses dokumentasi Matter dan referensi dukungan untuk mencari bantuan.
2. Lihat Analytics Google Home
Pemantauan performa sangat penting untuk keberhasilan integrasi dengan ekosistem Google Home. Kami menyediakan serangkaian alat pemantauan untuk developer smart home di Google Cloud Platform. Anda dapat menggunakan alat ini untuk mengukur performa project.
Mengakses metrik project
- Langkah pertama untuk mengakses data Anda adalah memeriksa dasbor Google Home, dengan login ke Google Cloud Console dan membuka Operasi > Pemantauan > Dasbor.
Ada sejumlah dasbor yang tersedia untuk project Anda (termasuk produk GCP lainnya). Dasbor yang disediakan untuk smart home dilengkapi dengan awalan Google Home Analytics.
Saat ini kami memiliki dasbor umum yang mencakup seluruh project Anda, serta dasbor untuk integrasi tertentu (Cloud, Lokal, Matter) atau jenis perangkat (Kamera). Dasbor ini hanya berisi data jika Anda memiliki integrasi jenis yang sesuai, beserta project yang berfungsi yang memenuhi permintaan.
Saat membuka salah satu dasbor ini, Anda akan melihat serangkaian diagram yang terlihat seperti berikut:
Dasbor Google Home berisi berbagai diagram yang menampilkan detail peristiwa yang terkait dengan project Anda. Dengan setiap dasbor integrasi, Anda akan melihat diagram yang menunjukkan jumlah total permintaan yang ditangani oleh project Anda, diagram yang menunjukkan tingkat keberhasilan untuk jenis integrasi tersebut, serta beberapa diagram yang menunjukkan jenis dan karakteristik perangkat yang terlibat. Selain itu, dengan Matter Anda memiliki kumpulan diagram yang melacak keberhasilan komisi, serta peluncuran update di perangkat Anda.
Perhatikan bahwa tampilan default dengan diagram yang Anda lihat di dasbor Google Home Analytics hanyalah tampilan yang kami buat untuk project Anda menggunakan data metrik smart home. Anda juga dapat menggunakan Metrics Explorer untuk membuat diagram sendiri dari metrik yang sama dan menyimpannya di dasbor kustom.
Mengakses log error
Logs Explorer adalah kumpulan alat untuk bekerja dengan log peristiwa yang dibuat pada project. Layanan ini dapat diakses di Google Cloud Console dengan membuka Operations > Logging > Logs Explorer.
Setelah membuka Logs Explorer, Anda akan mendapatkan tampilan yang terlihat seperti berikut:
Jendela penjelajah berisi berbagai alat untuk melihat, memfilter, membuat kueri, dan menganalisis log. Secara default, tampilan ini menunjukkan log yang dibuat dari semua sistem yang tersedia untuk project Anda, termasuk log yang dibuat di luar Smart Home. Itu sebabnya penting untuk menggunakan log ini dengan memfilter peristiwa yang ingin Anda debug. Kita akan membahas ini lebih lanjut di bagian proses debug.
3. Men-debug Masalah Komisi
Jenis metrik pertama yang akan kita lihat adalah tentang peristiwa komisi. Komisi merujuk pada serangkaian langkah yang diperlukan bagi pengguna untuk menyiapkan perangkat Matter untuk pertama kalinya.
Selama penetapan perangkat, serangkaian interaksi terjadi antara perangkat Matter, aplikasi Google Home, dan matter Matter. Gambar berikut menunjukkan beberapa peristiwa ini:
Anda dapat memeriksa halaman komisi dari Matter Primer untuk mempelajari lebih lanjut setiap langkah ini. Di bagian ini, kami akan membahas alat dan teknik untuk men-debug masalah komisi.
Gunakan Analytics Google Home
Kami telah membuat kumpulan metrik bagi Anda untuk menyelidiki masalah komisi dengan melacak peristiwa dan memahami pada tahap mana kesalahan tersebut mungkin terjadi. Anda dapat menemukannya di Dasbor Integrasi Materi, seperti yang telah dibahas di bagian sebelumnya.
Diagram di dasbor ini memberikan data tentang komisi perangkat:
Diagram jumlah perangkat menampilkan jumlah upaya penugasan oleh pengguna pada tanggal tertentu. Tingkat keberhasilan menunjukkan tingkat keberhasilan yang dirasakan untuk peristiwa ini di pihak Google. Setiap upaya komisi menghasilkan serangkaian peristiwa dengan status terkait. Saat terjadi error pada salah satu status ini, error juga akan dicatat dalam diagram perincian error.
Komisi Negara Bagian:
- DISERTAKAN_COM_SIONING
- ONBOARDING_PAYLOAD_GENERASI
- DISKON_LOCAL_DISUKAI
- KESUKSESAN_KESALAHAN_HASIL
- NOC_ADD_BERHASIL LENGKAP
- COMMISSIONING_COMPLETE
Untuk melihat versi mendetail peristiwa ini, buka Operasi > Logging > Logs Explorer. Untuk memfilter error komisi, Anda dapat menelusuri "clientUpdateLog" yang digabungkan dengan "severity>=ERROR" di kolom kueri.
Log error komisi untuk Matter terlihat seperti ini:
{
"insertId": "1a32ry0f6xpzzn",
"jsonPayload": {
"clientUpdateLog": {
"MatterUpdate": {
"reportedProductId": 55,
"sessionId": "1584879052892229997",
"reportedVendorId": 4800,
"commissioningState": "GENERIC_COMMISSIONING_ERROR",
"status": "GENERIC_ERROR"
}
}
},
"resource": {
"type": "assistant_action_project",
"labels": {
"project_id": "<project-id>"
}
},
"timestamp": "2023-03-01T07:09:55.216425297Z",
"severity": "ERROR",
"logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
"receiveTimestamp": "2023-03-01T07:09:55.216425297Z"
}
Selain status komisi dan kode status, log error berisi stempel waktu untuk error yang ditangkap, serta ID Produk Matter yang memungkinkan Anda mengidentifikasi produk mana yang menyebabkan error. Kumpulan log yang dihasilkan dari upaya komisi yang sama akan berbagi sessionId.
Menggunakan metrik dari Google Home Analytics memberi Anda ide awal pada tahap mana masalah tersebut mungkin terjadi. Untuk menemukan penyebab utama error pembuatan perangkat, terkadang Anda mungkin perlu melakukan proses debug tambahan menggunakan log yang dibuat oleh perangkat seluler yang digunakan dalam proses komisi. Untuk masalah ini, Anda memerlukan Android Debug Bridge.
Menggunakan Android Debug Bridge (ADB)
Cara lain untuk memecahkan masalah komisi adalah dengan menggunakan alat command line Android Debug Bridge (ADB). Karena komisi terutama ditangani antara perangkat seluler dan perangkat Matter, Anda dapat menggunakan alat ADB untuk mengakses log yang dibuat oleh aplikasi Google Home selama pengiriman.
Menginstal alat platform
ADB hadir sebagai bagian dari Android SDK Platform Tools, yang dapat diinstal dengan Android Studio atau melalui alat command line sdkmanager.
Setelah Anda berhasil menginstal alat platform pada sistem, verifikasi ADB dengan memeriksa nomor versi dari terminal menggunakan perintah berikut:
$ adb -- version
Ini akan menampilkan nomor versi utilitas ADB yang terinstal tanpa error.
Mengaktifkan proses debug USB
Berikutnya adalah mengaktifkan proses debug USB di perangkat Android Anda.
Pertama, ikuti langkah-langkah untuk mengaktifkan opsi developer di perangkat, lalu aktifkan proses debug USB.
Hal ini memungkinkan ADB mengakses log yang dihasilkan oleh aplikasi yang saat ini berjalan di perangkat.
Mengambil ID perangkat
- Jalankan server ADB dengan perintah berikut:
$ adb start-server
- Hubungkan ponsel Anda ke komputer yang menjalankan server ADB.
Anda mungkin mendapatkan pesan peringatan di ponsel tentang proses debug USB, yang menanyakan apakah Anda ingin mengizinkan komputer mengakses informasi dari ponsel:
- Jika Anda mendapatkan pesan peringatan ini, klik Izinkan.
- Jalankan perintah list devices dari terminal untuk melihat apakah komputer Anda dapat mengakses ponsel melalui ADB, menggunakan perintah berikut:
$ adb devices
Tindakan ini akan memberikan respons seperti ini:
List of devices attached <phone-id> device
<phone-id> adalah string alfanumerik yang mengidentifikasi perangkat Anda secara unik.
- Ingat nilai
<phone-id>untuk digunakan pada langkah berikutnya.
Mengumpulkan informasi sistem
Selanjutnya adalah memeriksa informasi versi aplikasi dan sistem di perangkat Anda.
- Untuk memeriksa versi OS Android:
$ adb -s <phone-id> shell getprop ro.build.version.release
- Untuk memeriksa versi Aplikasi Google Home:
$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName
- Untuk memeriksa versi Layanan Google Play:
$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"
- Untuk memeriksa apakah Anda memiliki modul kontrol Rumah / Materi Iklan melalui Layanan Play:
$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"
Pastikan nilai yang ditampilkan ini didukung oleh ekosistem kami. Saat menghubungi dukungan terkait kegagalan komisi, harap selalu sertakan informasi sistem di tiket dukungan Anda.
Kumpulkan log error
Selanjutnya, mulai proses pengumpulan log, lalu lakukan langkah-langkah komisi untuk membuat peristiwa error yang ingin Anda debug.
- Jalankan perintah berikut dengan memberikan
<phone-id>Anda, serta<file-name>tempat log akan disimpan di komputer Anda (misalnyadebug_file.txt).
$ adb -s <phone-id> logcat > <file-name>
Tindakan ini akan segera memulai proses logging. File dengan nama yang diberikan akan dibuat jika belum ada, dan log dari ponsel akan ditambahkan ke file setelah setiap peristiwa.
Lanjutkan dengan langkah-langkah komisi dengan perangkat Matter.
- Setelah Anda mencapai error yang ingin di-debug, hentikan logging dengan menekan
Control+Cdi jendela terminal yang berjalan.
Log Anda kini telah disimpan di file logging <file-name>. Karena proses ini mencatat log dari setiap proses yang berjalan yang dilacak di perangkat, akan ada banyak log dalam file ini. Itulah mengapa Anda harus selalu memanfaatkan log ini dengan menelusuri entri yang diperlukan.
Menganalisis log error
Proses komisii ditangani melalui subsistem yang disebut MatterCommissioner dalam GHA.
- Dengan mengikuti strategi utama yang digunakan saat menganalisis error komisi, cari error yang dibuat oleh subsistem MatterCommissioner dengan perintah berikut:
$ grep "MatterCommissioner" <file-name>
Ini menghasilkan output yang berisi peristiwa dari proses komisi.
- Jika perangkat Matter menggunakan Thread, Anda juga dapat mencari error yang dihasilkan oleh subsistem Thread melalui perintah berikut:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>
Saat Anda menganalisis file log yang dihasilkan oleh proses proses debug ADB, cari juga pola tertentu. Banyak error yang terjadi saat memasukkan string "commissioning failure" dalam pesan error-nya.
- Cari pesan kegagalan komisi dengan perintah berikut:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"
4. Men-debug Masalah Kontrol Perangkat
Setelah menyiapkan dan mendaftarkan perangkat Matter ke ekosistem Google Home, pengguna dapat mengeluarkan perintah melalui suara menggunakan Asisten Google (misalnya, "Ok Google, nyalakan lampu di ruang keluarga") atau dengan menggunakan UI di Aplikasi Home atau perangkat layar Google Nest.
Karena spesifikasi kontrol antara perangkat akhir dan Google Hub dimediasi oleh Matter, diharapkan jumlah error pada sisi kontrol perangkat lebih sedikit. Terlepas dari itu, kami juga menyediakan metrik dan log untuk melakukan debug pada jenis masalah tersebut.
Menggunakan metrik
Di Matter Integration Dashboard, Anda akan melihat beberapa metrik terkait kontrol perangkat. Ada tiga diagram yang penting untuk menilai performa perangkat Anda di lapangan:
Selama masalah kontrol, Anda biasanya melihat tren penurunan dalam persentase keberhasilan dan tren naik dalam diagram perincian error. Diagram perincian error menunjukkan error yang ditangkap oleh Google Nest Hub terkait alasan kegagalan upaya kontrol perangkat.
Menggunakan log
Setiap masalah kontrol perangkat Matter juga menghasilkan log error dalam sistem. Error ini dapat difilter dari Logs Explorer dengan menelusuri "executionLog".
Log error kontrol perangkat Matter terlihat seperti berikut:
{
"insertId": "1a32ry0f6xpzzn",
"jsonPayload": {
"executionLog": {
"executionResults": [
{
"executionType": "MATTER",
"latencyMsec": "6000",
"actionResults": [
{
"action": {
"actionType": "ONOFF_OFF",
"trait": "TRAIT_ON_OFF"
},
"status": {
"externalDebugString": "No message was received before the deadline.",
"statusType": "RESPONSE_TIMEOUT",
"fallbackToCloud": false,
"isSuccess": false
},
"device": {
"deviceType": "OUTLET"
}
}
],
"requestId": "1487232799486580805"
}
]
},
"locale": "en-US"
},
"resource": {
"type": "assistant_action_project",
"labels": {
"project_id": "<project-id>"
}
},
"timestamp": "2023-03-01T15:47:27.311673018Z",
"severity": "ERROR",
"logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
"receiveTimestamp": "2023-03-01T15:47:27.311673018Z"
}
Setiap log error berisi stempel waktu, jenis perangkat, dan fitur, serta error yang terkait dengan permintaan kontrol di statusType. Banyak error kontrol juga mencakup externalDebugString, pesan error singkat yang menjelaskan error tersebut.
5. Men-debug Fitur Lainnya
Sejauh ini Anda telah mempelajari cara menangani komisi dan kontrol perangkat untuk Matter. Ada juga fitur lain dalam ekosistem tersebut yang dapat Anda gunakan dengan teknik yang direkomendasikan untuk memastikan integrasi yang berkualitas.
Melacak update OTA
Guna melacak rilis untuk update over the air (OTA) ke perangkat Matter yang dikeluarkan oleh Google Home, kami menyediakan kumpulan metrik yang menunjukkan hardware dan versi software untuk perangkat yang ada di lapangan.
Setelah Anda melakukan update dari konsol, pantau metrik berikut:
Anda akan melihat bahwa pada hari-hari setelah rilis, semakin banyak perangkat di kolom tersebut yang mendapatkan versi software baru yang dikaitkan dengan rilis software OTA Anda.
6. Dukungan Pencari
Google menyediakan alat dan dokumentasi bagi Anda untuk men-debug masalah Matter. Namun, karena ekosistem Matter masih baru, akan ada masalah yang tidak tercakup dalam resource ini. Untuk kasus ini, Anda dapat selalu menghubungi kami atau komunitas untuk mencari dukungan.
Kunjungi channel developer
Ada tiga saluran developer yang aktif dipantau di Google:
Meskipun setiap saluran ini dipantau oleh tim yang sama secara berkala, ada beberapa perbedaan utama terkait kapan harus digunakan.
- Stack Overflow: Anda dapat menghubungi kami dan komunitas developer Smart Home untuk mengajukan pertanyaan terkait penerapan atau untuk mendapatkan panduan. Saluran ini cocok untuk menanyakan cara memecahkan masalah atau menerapkan fitur tertentu.
- Pelacak Masalah: Ini adalah sistem pelacak masalah resmi yang dijalankan Google, tempat audiens eksternal dapat melaporkan error pada ekosistem. Menyediakan alat web untuk melampirkan file dan berbagi info sensitif saat diperlukan. Penggunaan Issue Tracker adalah cara terbaik untuk melaporkan masalah ekosistem atau membagikan permintaan fitur.
- Forum Developer: Untuk meminta panduan dari pakar komunitas dan dukungan resmi Google, Anda dapat menghubungi kami melalui Forum Developer Nest. Forum ini cocok untuk \ mendapatkan panduan resmi terkait pengembangan.
Daftar ke newsletter developer
Selain mengunjungi channel developer untuk mengajukan pertanyaan, kami juga merilis newsletter tiga bulanan yang menyoroti fitur baru dan memberikan berita tentang kondisi ekosistem Google Smart Home.
Anda dapat menggunakan formulir pendaftaran untuk menerima newsletter developer.
7. Selamat
Selamat! Anda telah berhasil mempelajari cara men-debug integrasi Matter menggunakan alat dan teknik yang kami rekomendasikan. Kami harap Anda berhasil membangun integrasi Matter dengan Google Home.
Langkah berikutnya
Coba latihan berikut dan jelajahi referensi tambahan:
- Selain menggunakan analisis untuk memecahkan masalah, Anda juga dapat menggunakan Test Suite untuk menguji integrasi Anda terhadap potensi masalah.
- Setelah integrasi Anda siap dibagikan kepada dunia, langkah selanjutnya adalah mendapatkan sertifikasi WWGH project Anda. Untuk melakukannya, Anda dapat mengikuti langkah-langkah di halaman Sertifikasi.