Men-debug Integrasi Matter

1. Sebelum memulai

Matter menawarkan pengalaman penyiapan dan kontrol perangkat lintas platform yang lancar bagi pengguna akhir. Hal ini terutama dapat dilakukan karena beberapa komponen ekosistem yang bekerja bersama di balik layar. Memecahkan masalah sistem seperti ini sering kali terasa sulit bagi developer baru, jadi 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 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 tersebut.

Prasyarat

• Selesaikan panduan Mulai menggunakan Matter dengan penyiapan perangkat dan project Matter yang berfungsi
• 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 memilah-milah error dengan mengakses log error dan mengumpulkan informasi.
• Cara mengakses dokumentasi Matter dan sumber dukungan untuk mendapatkan bantuan.

2. Melihat Analisis Google Home

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 performa project 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 (Cloud, Lokal, Matter) atau jenis perangkat (Kamera) tertentu. Dasbor ini hanya berisi data jika Anda memiliki integrasi jenis yang sesuai, beserta project yang berfungsi dan 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. Di setiap dasbor integrasi, Anda akan melihat diagram yang menampilkan jumlah total permintaan yang ditangani oleh project Anda, diagram yang menampilkan rasio 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 aktivasi, 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 pokok yang sama dan menyimpannya di dasbor kustom.

Mengakses log error

Logs Explorer adalah kumpulan alat untuk menangani log peristiwa yang dihasilkan di project. Logs Explorer dapat diakses di Konsol Google Cloud 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 Penyiapan

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

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

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

Menggunakan Google Home Analytics

Kami telah membuat serangkaian metrik untuk Anda selidiki masalah aktivasi dengan melacak peristiwa dan memahami pada tahap mana kesalahan mungkin terjadi. Anda dapat menemukannya di Dasbor Integrasi Matter, seperti yang kami bahas di bagian sebelumnya.

Diagram di dasbor ini memberikan data tentang aktivasi perangkat:

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

Negara Bagian yang Melakukan 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 Operations > Logging > Logs Explorer. Untuk memfilter error aktivasi, Anda dapat menelusuri "clientUpdateLog" yang digabungkan dengan "severity>=ERROR" di kolom kueri.

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

Menggunakan metrik dari Google Home Analytics akan memberi Anda gambaran awal tentang tahap terjadinya masalah. Untuk menemukan akar penyebab error aktivasi perangkat, terkadang Anda mungkin perlu melakukan proses debug tambahan menggunakan log yang dihasilkan oleh perangkat seluler yang digunakan dalam proses aktivasi. Untuk melakukannya, Anda memerlukan Android Debug Bridge.

Menggunakan Android Debug Bridge (ADB)

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

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 Anda, verifikasi ADB dengan memeriksa nomor versi dari terminal menggunakan perintah berikut:

$ adb -- version

Perintah 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 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 Anda mengakses informasi dari ponsel Anda:

3. Jika Anda mendapatkan pesan peringatan ini, klik Izinkan.
4. Keluarkan 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 yang mirip dengan 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 pada langkah berikutnya.

Mengumpulkan informasi sistem

Selanjutnya, periksa 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 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 aktivasi, selalu sertakan informasi sistem dalam tiket dukungan Anda.

Mengumpulkan log error

Selanjutnya, mulai proses pengumpulan log, lalu ikuti langkah-langkah aktivasi 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 (mis. debug_file.txt).

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

Tindakan ini akan segera memulai proses pencatatan log. File dengan nama yang diberikan akan dibuat jika belum ada, dan log dari ponsel akan ditambahkan ke file setelah setiap peristiwa.

Lanjutkan langkah-langkah aktivasi 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 yang dilacak di perangkat, akan ada banyak log dalam file ini. Oleh karena itu, Anda harus selalu memanfaatkan log ini dengan menelusuri entri yang Anda butuhkan.

Menganalisis log error

Proses commissioning ditangani melalui subsistem yang disebut MatterCommissioner dalam GHA.

1. Dengan mengikuti strategi utama yang digunakan saat menganalisis error penyiapan, 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 dihasilkan oleh subsistem Thread melalui perintah berikut:

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

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

3. Cari pesan kegagalan aktivasi 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 ekosistem Google Home, mereka dapat mengeluarkan perintah dengan suara menggunakan Asisten Google (misalnya, "Ok Google, nyalakan lampu di ruang tamu") atau menggunakan UI di Aplikasi Home atau perangkat layar Google Nest.

Karena spesifikasi kontrol antara perangkat akhir dan Hub Google dimediasi oleh Matter, diharapkan akan ada lebih sedikit error di sisi kontrol perangkat. Terlepas dari itu, kami 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 penting untuk menilai performa perangkat Anda di lapangan:

Selama masalah kontrol, Anda biasanya melihat tren penurunan pada persentase keberhasilan dan tren peningkatan pada diagram perincian error. Diagram perincian error menunjukkan error yang direkam oleh Google Nest Hub terkait alasan upaya kontrol perangkat gagal.

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 sifat, serta error yang terkait dengan permintaan kontrol di statusType. Banyak error kontrol juga menyertakan externalDebugString, pesan error singkat yang menjelaskan penyebab error.

5. Men-debug Fitur Lainnya

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

Memantau update OTA

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

Setelah Anda melakukan update dari konsol, perhatikan metrik berikut:

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

6. Mencari Dukungan

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

Mengunjungi saluran developer

Ada tiga saluran developer yang dipantau secara aktif dalam Google:

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

• Stack Overflow: Anda dapat menghubungi kami dan komunitas developer Smart Home untuk mengajukan pertanyaan terkait penerapan atau mencari panduan. Saluran ini paling 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. 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 kami melalui Forum Developer Nest. Forum ini paling cocok untuk \ mendapatkan panduan resmi untuk pengembangan.

Mendaftar untuk menerima newsletter developer

Selain mengunjungi saluran developer untuk mengajukan pertanyaan, kami juga merilis newsletter triwulanan 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 berhasil membuat integrasi Matter dengan Google Home.

Langkah berikutnya

Coba latihan berikut dan pelajari 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 berikutnya adalah mendapatkan Sertifikasi WWGH untuk project Anda. Untuk melakukannya, Anda dapat mengikuti langkah-langkah di halaman Sertifikasi.