Men-debug Integrasi Matter

1. Sebelum memulai

Matter menawarkan penyiapan perangkat lintas platform yang lancar dan pengalaman kontrol untuk pengguna akhir. Hal ini terutama dimungkinkan karena beberapa komponen ekosistem yang bekerja sama satu sama lain di balik layar. Memecahkan masalah sistem seperti ini sering kali menakutkan bagi developer baru, jadi kami mengembangkan serangkaian alat dan teknik untuk memudahkan Anda sebagai developer Matter dengan Google Home.

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

Sebagai developer, Anda harus dapat memitigasi masalah yang Anda alami selama siklus pengembangan perangkat. Setelah meluncurkan project, Anda perlu memantau tren masalah untuk perangkat di lapangan secara gabungan, dan memperbaikinya melalui update software. Codelab ini membahas teknik yang dapat Anda gunakan untuk kedua tujuan ini.

Prasyarat

• Selesaikan panduan Memulai Matter dengan project Matter yang berfungsi dan penyiapan perangkat
• Memiliki ponsel Android yang dapat Anda hubungkan ke workstation (untuk log ADB)

Yang akan Anda pelajari

• Cara menggunakan alat analisis untuk Smart Home guna memantau masalah Matter dalam skala besar.
• Cara melakukan triage error dengan mengakses log error dan mengumpulkan informasi.
• Cara mengakses dokumentasi dan referensi dukungan Matter untuk mendapatkan bantuan.

2. Melihat Analytics Google Home

Pemantauan performa sangat penting untuk keberhasilan integrasi dengan ekosistem Google Home. Kami menyediakan serangkaian alat pemantauan kepada developer smart home di Google Cloud Platform. Anda dapat menggunakan alat ini untuk mendapatkan ukuran performa project.

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 jenis yang sesuai, beserta project yang berfungsi untuk 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 untuk peristiwa yang terkait dengan project Anda. Dengan setiap dasbor integrasi, Anda akan melihat diagram yang menampilkan jumlah total permintaan yang ditangani oleh project Anda, diagram yang menampilkan tingkat keberhasilan untuk jenis integrasi tersebut, dan beberapa diagram yang menampilkan jenis dan karakteristik perangkat yang terlibat. Selain itu, dengan Matter, Anda memiliki serangkaian diagram yang melacak keberhasilan commissioning, serta peluncuran update di perangkat.

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 menggunakan log peristiwa yang dihasilkan di project. Alat 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 sebabnya 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 Komisi

Jenis metrik pertama yang akan kita lihat adalah tentang peristiwa commissioning Matter. Commissioning mengacu pada serangkaian langkah yang diperlukan 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 commissioning dari Primer Matter untuk mempelajari lebih lanjut setiap langkah ini. Di bagian ini, kita akan membahas alat dan teknik untuk men-debug masalah komisi.

Menggunakan Google Home Analytics

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

Diagram di dasbor ini memberikan data tentang commissioning perangkat:

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

Status Komisi:

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

Untuk melihat versi mendetail dari peristiwa ini, buka Operations > Logging > Logs Explorer. Untuk memfilter error komisi, Anda dapat menelusuri "clientUpdateLog" yang digabungkan dengan "severity>=ERROR" di kolom kueri.

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

Menggunakan metrik dari Google Home Analytics akan memberi Anda gambaran awal tentang tahap terjadinya masalah. Untuk menemukan akar masalah error komisi perangkat, terkadang Anda mungkin perlu melakukan proses debug tambahan menggunakan log yang dihasilkan oleh perangkat seluler yang digunakan dalam proses komisi. 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 dihasilkan oleh aplikasi Google Home selama commissioning.

Menginstal alat platform

ADB disertakan sebagai bagian dari Android SDK Platform Tools, yang dapat diinstal dengan Android Studio atau melalui alat command line sdkmanager.

Setelah berhasil menginstal alat platform di sistem, verifikasi ADB dengan memeriksa nomor versi dari terminal dengan perintah berikut:

$ adb -- version

Tindakan ini akan menampilkan nomor versi utilitas ADB yang diinstal tanpa error.

Mengaktifkan proses debug USB

Langkah berikutnya adalah mengaktifkan proses debug USB di perangkat Android Anda.

Pertama, ikuti langkah-langkah untuk mengaktifkan opsi developer di perangkat Anda, lalu aktifkan proses debug USB.

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

Mengambil 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 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 berikut:

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 pada langkah berikutnya.

Mengumpulkan informasi sistem

Berikutnya adalah memeriksa informasi versi aplikasi dan sistem di perangkat Anda.

• Untuk memeriksa versi Android OS:

$ 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 Home/Matter 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 commissioning, selalu sertakan informasi sistem dalam tiket dukungan Anda.

Kumpulkan log error

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

1. Jalankan perintah berikut dengan memberikan <phone-id> Anda, serta <file-name> tempat log akan disimpan di komputer (misalnya, debug_file.txt).

$ adb -s <phone-id> logcat > <file-name>

Tindakan ini akan langsung 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 commissioning dengan perangkat Matter Anda.

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

Log Anda kini akan disimpan dalam file logging <file-name>. Karena proses ini mencatat log dari setiap proses yang berjalan dan dilacak di perangkat, akan ada banyak log dalam file ini. Itulah sebabnya Anda harus selalu menggunakan log ini dengan menelusuri entri yang Anda perlukan.

Menganalisis log error

Proses commissioning ditangani melalui subsistem yang disebut MatterCommissioner 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 Anda menggunakan Thread, Anda juga dapat mencari error yang dibuat oleh subsistem Thread melalui perintah berikut:

$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

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

3. Telusuri pesan kegagalan commissioning dengan perintah berikut:

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

4. Men-debug Masalah Kontrol Perangkat

Setelah pengguna menyiapkan dan mengaktifkan 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 diharapkan akan lebih sedikit. Meskipun demikian, kami juga menyediakan metrik dan log untuk Anda men-debug jenis masalah ini.

Menggunakan metrik

Di Dasbor Integrasi Matter, 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 peningkatan tren di diagram perincian error. Diagram perincian error menampilkan error yang direkam oleh Google Nest Hub terkait alasan kegagalan upaya kontrol perangkat.

Menggunakan log

Setiap masalah kontrol perangkat Matter juga 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. Men-debug Fitur Lainnya

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

Melacak update OTA

Untuk melacak rilis update Over-the-air (OTA) ke perangkat Matter yang dikeluarkan oleh Google Home, kami menyediakan serangkaian metrik yang menampilkan versi hardware dan software untuk perangkat di lapangan.

Setelah Anda melakukan pembaruan dari konsol, perhatikan metrik berikut:

Anda akan melihat bahwa dalam beberapa hari setelah rilis, semakin banyak perangkat di lapangan yang mendapatkan versi software baru yang terkait dengan rilis software OTA Anda.

6. Mendapatkan Dukungan

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

Kunjungi channel developer

Ada tiga saluran developer yang dipantau secara aktif di Google:

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

• Stack Overflow: Anda dapat menghubungi kami dan komunitas developer Smart Home jika ada pertanyaan terkait penerapan atau untuk meminta panduan. Channel ini paling cocok untuk bertanya 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. Fitur ini menyediakan alat web untuk melampirkan file dan membagikan info sensitif jika 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 melalui Forum Developer Nest. Forum ini paling cocok untuk \ mendapatkan panduan resmi untuk pengembangan.

Daftar ke newsletter developer

Selain mengunjungi saluran developer untuk mengajukan pertanyaan, kami juga merilis newsletter kuartalan yang menyoroti fitur baru dan memberikan berita tentang status ekosistem Google Smart Home.

Anda dapat menggunakan formulir pendaftaran untuk menerima newsletter developer.

7. Selamat

Selamat! Anda berhasil mempelajari cara men-debug integrasi Matter menggunakan alat dan teknik yang kami rekomendasikan. Semoga Anda menikmati proses pembuatan 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 untuk dibagikan kepada dunia, langkah selanjutnya adalah mendapatkan proyek Anda yang Tersertifikasi WWGH. Untuk melakukannya, Anda dapat mengikuti langkah-langkah di halaman Sertifikasi.