Men-debug Integrasi Matter

1. Sebelum memulai

Matter menawarkan penyiapan perangkat dan pengalaman kontrol lintas platform yang lancar bagi pengguna akhir. Hal ini terutama dapat terjadi karena adanya beberapa komponen ekosistem yang bekerja sama satu sama lain di balik layar. Sistem pemecahan masalah seperti ini sering kali menyulitkan developer baru. Oleh karena itu, kami mengembangkan serangkaian alat dan teknik untuk mempermudah hidup Anda sebagai developer Matter dengan Google Home.

Ada tiga komponen utama untuk Matter yang dibahas dalam codelab ini. Untuk setiap sistem ini, Google menyediakan kumpulan analisis pemecahan masalah untuk developer yang dikumpulkan dari ponsel dan hub:

Sebagai developer, sangat penting bagi Anda untuk dapat memitigasi masalah yang Anda alami selama siklus pengembangan perangkat. Setelah meluncurkan proyek, Anda perlu memantau tren masalah untuk perangkat di lapangan secara agregat, dan memperbaikinya melalui pembaruan perangkat lunak. Codelab ini membahas teknik yang dapat Anda gunakan untuk kedua tujuan tersebut.

Prasyarat

• Selesaikan panduan Mulai menggunakan Matter dengan menyiapkan 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 menentukan prioritas error dengan mengakses log error dan mengumpulkan informasi.
• Cara mengakses dokumentasi dan referensi dukungan Matter untuk mencari bantuan.

2. Melihat Google Home Analytics

Memantau 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 kinerja proyek Anda.

Mengakses metrik project

• Langkah pertama untuk mengakses data Anda adalah memeriksa dasbor Google Home, dengan login ke Konsol Google Cloud 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 dari jenis yang sesuai, bersama dengan 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 proyek Anda, diagram yang menunjukkan tingkat keberhasilan untuk jenis integrasi tersebut, dan beberapa diagram yang menunjukkan jenis dan karakteristik perangkat yang terlibat. Selain itu, dengan Matter Anda memiliki serangkaian diagram yang melacak keberhasilan commissioning, 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 dasar yang sama dan menyimpannya di dasbor kustom.

Mengakses log error

Logs Explorer adalah kumpulan alat untuk bekerja dengan log peristiwa yang dibuat pada project. Log ini dapat diakses di Google Cloud Console dengan membuka Operations > Logging > Logs Explorer.

Setelah membuka Logs Explorer, Anda akan melihat tampilan seperti berikut:

Jendela penjelajah berisi berbagai alat untuk melihat, memfilter, membuat kueri, dan menganalisis log. Secara default, tampilan ini menampilkan log yang dihasilkan dari semua sistem yang tersedia untuk project Anda, termasuk log yang dihasilkan di luar Smart Home. Itulah mengapa penting untuk menggunakan log ini dengan memfilter peristiwa yang ingin Anda debug. Kita akan membahasnya lebih lanjut di bagian proses debug.

3. Men-debug Masalah Commissioning

Jenis metrik pertama yang akan kita lihat adalah tentang peristiwa commissioning Matter. Commissioning mengacu pada serangkaian langkah yang diperlukan bagi pengguna untuk menyiapkan perangkat Matter untuk pertama kalinya.

Selama commissioning perangkat, serangkaian interaksi terjadi antara perangkat Matter, aplikasi Google Home, dan fabric Matter. Gambar berikut menunjukkan beberapa peristiwa ini:

Anda dapat memeriksa halaman pengiriman dari Matter Primer untuk mempelajari setiap langkah ini lebih lanjut. Di bagian ini, kita akan membahas alat dan teknik untuk men-debug masalah commissioning.

Menggunakan Google Home Analytics

Kami telah membuat kumpulan metrik agar Anda dapat menyelidiki masalah commissioning dengan melacak peristiwa dan memahami pada tahap mana error mungkin terjadi. Anda dapat menemukannya di Dasbor Integrasi Matter, seperti yang kita bahas di bagian sebelumnya.

Diagram di dasbor ini memberikan data tentang commissioning perangkat:

Diagram jumlah perangkat menunjukkan jumlah upaya commissioning oleh pengguna pada tanggal tertentu. Tingkat keberhasilan menunjukkan tingkat keberhasilan yang dirasakan untuk acara ini di pihak Google. Setiap upaya commissioning menghasilkan kumpulan peristiwa dengan status terkait. Jika terjadi error di salah satu status ini, error tersebut juga akan dicatat dalam diagram perincian error.

Status Commissioning:

• COMMISSIONING_STARTED
• ONBOARDING_PAYLOAD_GENERATED
• LOCAL_DISCOVERY_SUCCESSFUL
• PASE_CONNECTION_SUCCESSFUL
• NOC_ADDED_SUCCESSFULLY
• COMMISSIONING_COMPLETE

Untuk melihat versi mendetail dari 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 commissioning untuk Matter akan 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 commissioning dan kode status, log error berisi stempel waktu untuk error yang terjadi, serta ID Produk Matter yang memungkinkan Anda mengidentifikasi produk mana yang menyebabkan error. Kumpulan log yang dihasilkan dari upaya commissioning yang sama memiliki sessionId yang sama.

Menggunakan metrik dari Google Home Analytics memberi Anda gambaran awal di tahap mana masalah mungkin terjadi. Untuk menemukan akar masalah error commissioning perangkat, terkadang Anda mungkin perlu melakukan proses debug tambahan menggunakan log yang dibuat oleh perangkat seluler yang digunakan dalam proses commissioning. Untuk itu, Anda memerlukan Android Debug Bridge.

Menggunakan Android Debug Bridge (ADB)

Cara lain untuk memecahkan masalah commissioning adalah dengan menggunakan alat command line Android Debug Bridge (ADB). Karena commissioning terutama ditangani antara perangkat seluler dan perangkat Matter, Anda dapat menggunakan alat ADB untuk mengakses log yang dibuat oleh aplikasi Google Home selama commissioning.

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

Nomor versi utilitas ADB yang terinstal akan ditampilkan 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 Anda, lalu mengaktifkan proses debug USB.

Hal ini memungkinkan ADB mengakses log yang dibuat oleh aplikasi yang sedang berjalan di perangkat.

Ambil ID perangkat

1. Jalankan server ADB dengan perintah berikut:

$ adb start-server

2. Hubungkan ponsel 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:

3. Jika Anda mendapatkan pesan peringatan ini, klik Izinkan.
4. Berikan perintah daftar perangkat dari terminal untuk melihat apakah komputer Anda dapat mengakses ponsel melalui ADB, menggunakan perintah berikut:

$ adb devices

Ini akan memberikan respons seperti ini:

List of devices attached
<phone-id>    device

<phone-id> Anda adalah string alfanumerik yang mengidentifikasi perangkat Anda secara unik.

5. Ingat nilai <phone-id> untuk digunakan di langkah berikutnya.

Mengumpulkan informasi sistem

Berikutnya 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 / Masalah 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 return ini didukung oleh ekosistem kami. Saat menghubungi dukungan terkait kegagalan komisi, selalu sertakan informasi sistem dalam tiket dukungan Anda.

Mengumpulkan log error

Selanjutnya, mulai proses pengumpulan log, lalu lakukan langkah-langkah commissioning untuk menghasilkan peristiwa error yang ingin Anda debug.

1. Jalankan perintah berikut dengan memberikan <phone-id> Anda, serta <file-name> tempat log akan disimpan di komputer Anda (misalnya, debug_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 tersebut setelah setiap peristiwa.

Lanjutkan dengan langkah-langkah commissioning dengan perangkat Matter Anda.

2. Setelah menemukan error yang ingin Anda debug, hentikan logging dengan menekan Control+C di jendela terminal yang sedang berjalan.

Log Anda sekarang seharusnya disimpan dalam file logging <file-name>. Karena proses ini mencatat log dari setiap proses yang berjalan yang terlacak di perangkat, akan ada banyak log dalam file ini. Itulah mengapa Anda harus selalu memanfaatkan log ini dengan menelusuri entri yang Anda butuhkan.

Menganalisis log error

Proses Commissioning ditangani melalui subsistem yang disebut MatterCommissioner di dalam GHA.

1. Dengan mengikuti strategi utama yang digunakan saat menganalisis error commissioning, cari error yang dihasilkan oleh subsistem MatterCommissioner dengan perintah berikut:

$ grep "MatterCommissioner" <file-name>

Tindakan ini akan menghasilkan output yang berisi peristiwa dari proses commissioning.

2. 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>

Selagi Anda menganalisis file log yang dihasilkan oleh proses debug ADB, cari juga pola-pola tertentu. Banyak error commissioning menyertakan string "commissioning failure" dalam pesan error-nya.

3. Telusuri pesan kegagalan commissioning dengan perintah berikut:

$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"

4. Debug Masalah Kontrol Perangkat

Setelah pengguna menyiapkan dan memesan perangkat Matter ke dalam ekosistem Google Home, mereka dapat memberikan perintah melalui suara menggunakan Asisten Google (misalnya, "Ok Google, nyalakan lampu di ruang keluarga saya") atau dengan menggunakan UI di Aplikasi Home atau perangkat layar Google Nest.

Karena spesifikasi kontrol antara perangkat akhir dan Google Hub dimediasi oleh Matter, error di sisi kontrol perangkat diperkirakan akan lebih sedikit. Terlepas dari itu, kami juga menyediakan metrik dan log agar Anda dapat men-debug jenis masalah ini juga.

Menggunakan metrik

Di Dasbor Integrasi Matter, Anda akan melihat beberapa metrik terkait kontrol perangkat. Ada tiga diagram yang penting untuk menilai kinerja perangkat Anda di lapangan:

Selama masalah kontrol, Anda biasanya melihat tren turun dalam persentase keberhasilan dan tren naik di diagram perincian error. Diagram perincian error menunjukkan error yang ditangkap oleh Google Nest Hub terkait penyebab gagalnya upaya kontrol perangkat.

Menggunakan log

Setiap masalah kontrol perangkat Matter juga akan menghasilkan log error di 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 karakteristik, serta error yang terkait dengan permintaan kontrol di statusType. Banyak error kontrol juga menyertakan externalDebugString, pesan error singkat yang menjelaskan tentang error tersebut.

5. Debug Fitur Lainnya

Sejauh ini, Anda telah mempelajari cara menangani masalah commissioning dan kontrol perangkat untuk Matter. Ada juga fitur lain dalam ekosistem yang memungkinkan Anda menggunakan teknik yang kami rekomendasikan untuk memastikan integrasi yang berkualitas baik.

Melacak update OTA

Guna melacak rilis untuk update Over the air (OTA) ke perangkat Matter yang dikeluarkan oleh Google Home, kami memberikan kumpulan metrik yang menunjukkan versi hardware dan software untuk perangkat di lapangan.

Setelah Anda melakukan update dari konsol, pantau metrik berikut:

Anda akan melihat bahwa pada hari-hari setelah rilis, semakin banyak perangkat di bidang ini yang mendapatkan versi software baru yang terkait dengan rilis software OTA Anda.

6. Cari Dukungan

Google menyediakan alat dan dokumentasi bagi Anda untuk men-debug masalah Matter, tetapi karena ekosistem Matter masih baru, akan ada masalah yang tidak dibahas dalam referensi ini. Untuk kasus ini, Anda dapat menghubungi kami atau komunitas kapan saja untuk mencari dukungan.

Kunjungi saluran developer

Ada tiga saluran developer yang secara aktif dipantau di Google:

Meskipun setiap saluran ini dipantau oleh tim yang sama secara berkala, ada beberapa perbedaan utama terkait kapan harus menggunakan saluran yang mana.

• Stack Overflow: Anda dapat menghubungi kami dan komunitas developer Smart Home jika ada pertanyaan terkait penerapan atau untuk mencari panduan. Saluran ini paling cocok untuk bertanya tentang cara memecahkan masalah atau menerapkan fitur tertentu.
• Issue Tracker: Ini adalah sistem issue tracker resmi yang dijalankan Google, tempat audiens eksternal dapat melaporkan error pada ekosistem. Layanan ini menyediakan alat web untuk melampirkan file dan membagikan info sensitif saat diperlukan. Menggunakan Issue Tracker adalah cara terbaik untuk melaporkan masalah ekosistem atau membagikan permintaan fitur.
• Forum Developer: Untuk mendapatkan panduan dari dukungan resmi Google dan pakar komunitas, Anda dapat menghubungi kami melalui Forum Developer Nest. Forum ini paling cocok untuk \ mendapatkan panduan resmi pengembangan.

Daftar untuk menerima newsletter developer

Selain mengunjungi saluran 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. Semoga Anda dapat membangun integrasi Matter dengan Google Home.

Langkah berikutnya

Cobalah latihan berikut dan jelajahi sumber daya tambahan:

• Selain menggunakan analisis untuk memecahkan masalah, Anda juga dapat menggunakan Test Suite untuk menguji integrasi terhadap potensi masalah.
• Setelah integrasi Anda siap untuk dibagikan kepada dunia, langkah berikutnya adalah mendapatkan project Anda Bersertifikat WWGH. Untuk itu, Anda dapat mengikuti langkah-langkah di halaman Sertifikasi.