Konu Entegrasyonlarında Hata Ayıklama

1. Başlamadan önce

Matter, son kullanıcılar için platformlar arası sorunsuz bir cihaz kurulumu ve kontrol deneyimi sunar. Bu, temel olarak perde arkasında birbirleriyle birlikte çalışan birden fazla ekosistem bileşeni sayesinde mümkün olur. Bu tür sistemlerde sorun giderme, yeni geliştiriciler için genellikle göz korkutucu olabilir. Bu nedenle, Google Home ile Matter geliştiricisi olarak hayatınızı kolaylaştırmak için bir dizi araç ve teknik geliştirdik.

Matter'ın bu kod laboratuvarının kapsamındaki üç ana bileşeni vardır. Google, bu sistemlerin her biri için telefonlardan ve merkezlerden toplanan geliştiricilere yönelik bir sorun giderme analizi grubu sağlar:

Geliştirici olarak, cihaz geliştirme döngüsü boyunca karşılaştığınız sorunları azaltabilmeniz çok önemlidir. Projenizi kullanıma sunduktan sonra, sahadaki cihazlarla ilgili sorun trendlerini toplu olarak izlemeniz ve yazılım güncellemeleri aracılığıyla bu sorunları düzeltmeniz gerekir. Bu kod laboratuvarı, her iki amaç için de kullanabileceğiniz teknikleri kapsar.

Ön koşullar

• Çalışan bir Matter projesi ve cihaz kurulumuyla Matter'ı kullanmaya başlama kılavuzunu tamamlayın
• İş istasyonunuza bağlayabileceğiniz bir Android telefonunuz olmalıdır (ADB günlükleri için).

Neler öğreneceksiniz?

• Matter sorunlarını geniş ölçekte izlemek için Akıllı Ev analiz araçlarını kullanma.
• Hata günlüklerine erişerek ve bilgi toplayarak hataların önceliğini belirleme.
• Yardım almak için Matter dokümanlarına ve destek kaynaklarına erişme.

2. Google Home Analytics'i görüntüleme

Performansı izlemek, Google Home ekosistemiyle başarılı bir entegrasyon için kritik öneme sahiptir. Google Cloud Platform'da akıllı ev geliştiricilerine bir dizi izleme aracı sunuyoruz. Projenizin performansını ölçmek için bu araçları kullanabilirsiniz.

Proje metriklerine erişme

• Verilerinize erişmek için ilk adım, Google Cloud Console'a giriş yapıp İşlemler > İzleme > Kontrol panelleri'ne giderek Google Home kontrol panellerini kontrol etmektir.

Projenizde kullanabileceğiniz çeşitli kontrol panelleri (diğer GCP ürünleri dahil) vardır. Akıllı ev için sağlanan kontrol panelleri Google Home Analytics ön ekiyle gelir.

Şu anda projenizin tamamını kapsayan genel bir kontrol panelinin yanı sıra belirli entegrasyonlar (Bulut, Yerel, Matter) veya cihaz türleri (Kameralar) için kontrol panellerimiz mevcuttur. Bu kontrol panelleri yalnızca ilgili türde bir entegrasyonunuz ve istekleri karşılayan çalışan bir projeniz varsa veri içerir.

Bu kontrol panellerinden birini açtığınızda aşağıdaki gibi görünen bir dizi grafik görürsünüz:

Google Home kontrol panelleri, projenizle ilişkili etkinliklerin ayrıntılarını gösteren çeşitli grafikler içerir. Her entegrasyon kontrol panelinde, projeniz tarafından işlenen toplam istek sayısını gösteren bir grafik, söz konusu entegrasyon türünün başarı oranını gösteren bir grafik ve ilgili cihaz türlerini ve özelliklerini gösteren çeşitli grafikler bulunur. Ayrıca Matter ile, devreye alma işleminin başarısını ve cihazlarınızda güncellemelerin kullanıma sunulmasını izleyen bir dizi grafiğe sahip olursunuz.

Google Home Analytics kontrol panellerinde gördüğünüz grafiklerin yer aldığı varsayılan görünümün, akıllı ev metrikleri verilerini kullanarak projeniz için oluşturduğumuz bir görünüm olduğunu unutmayın. Aynı temel metriklerden kendi grafiklerinizi oluşturmak ve bunları özel kontrol panellerinize kaydetmek için Metrik Gezgini'ni de kullanabilirsiniz.

Erişim hatası günlükleri

Günlük Gezgini, bir projede oluşturulan olay günlükleriyle çalışan bir araç koleksiyonudur. Google Cloud Console'da İşlemler > Günlük Kaydı > Günlük Gezgini bölümünden erişilebilir.

Günlük Gezgini'ni açtığınızda aşağıdaki gibi bir görünüm görürsünüz:

Gezgin penceresi; günlükleri görüntülemek, filtrelemek, sorgulamak ve analiz etmek için çeşitli araçlar içerir. Bu görünümde varsayılan olarak, projenizde kullanılabilen tüm sistemlerden oluşturulan günlükler (Akıllı Ev dışında oluşturulan günlükler dahil) gösterilir. Bu nedenle, hata ayıklama yapmak istediğiniz etkinlikleri filtreleyerek bu günlükleri kullanmanız önemlidir. Bu konu hakkında daha fazla bilgiyi hata ayıklama bölümlerinde bulabilirsiniz.

3. Devreye Alma Sorunları İçin Hata Ayıklama

İnceleyeceğimiz ilk metrik türü, Matter kullanıma sunma etkinlikleriyle ilgilidir. Devreye alma, kullanıcının bir Matter cihazını ilk kez kurması için gereken bir dizi adımı ifade eder.

Cihazın devreye alınması sırasında Matter cihaz, Google Home uygulaması ve Matter kumaşı arasında bir dizi etkileşim gerçekleşir. Aşağıdaki resimde bu etkinliklerden bazıları gösterilmektedir:

Bu adımların her biri hakkında daha fazla bilgi edinmek için Matter Primer'daki devreye alma sayfasını inceleyebilirsiniz. Bu bölümde, devreye alma sorunlarında hata ayıklamaya yönelik araç ve teknikleri ele alacağız.

Google Home Analytics'i kullanabilirsiniz.

Etkinlikleri izleyerek ve hataların hangi aşamada gerçekleşebileceğini anlayarak devreye alma sorunlarını incelemeniz için bir dizi metrik oluşturduk. Bunları, önceki bölümde ele aldığımız gibi Matter Integration kontrol panelinde bulabilirsiniz.

Bu kontrol panelindeki grafikler, cihazların devreye alınmasıyla ilgili veriler sağlar:

Cihaz sayısı grafiğinde, kullanıcıların belirli bir tarihte gerçekleştirdiği devreye alma denemelerinin sayısı gösterilir. Başarı oranı, bu etkinliklerin Google tarafında algılanan başarı oranını gösterir. Her devreye alma denemesi, ilişkili durumlara sahip bir dizi etkinlik oluşturur. Bu durumlardan herhangi birinde ortaya çıkan hata, hata dökümü grafiğine de dahil edilir.

Devreye alma eyaletleri:

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

Bu etkinliklerin ayrıntılı bir sürümünü görüntülemek için İşlemler > Günlük Kaydı > Günlük Gezgini'ne gidin. Komisyon hatalarını filtrelemek için sorgu alanında "clientUpdateLog" ile birlikte "severity>=ERROR" ifadesini arayabilirsiniz.

Matter için devreye alma hata günlüğü aşağıdaki gibi görünür:

{
  "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"
}

Hata günlüğü, devreye alma durumuna ve durum koduna ek olarak, yakalanan hatanın zaman damgalarını ve hataya hangi ürünlerinizin neden olduğunu belirlemenize olanak tanıyan Matter ürün kimliğini içerir. Aynı komisyon denemesinden oluşturulan günlük grubu bir sessionId öğesini paylaşır.

Google Home Analytics'teki metrikleri kullanmak, sorunun hangi aşamada ortaya çıkabileceği konusunda size ilk fikir verir. Cihaz devreye alma hatalarının temel nedenini bulmak için bazen devreye alma sürecinde kullanılan mobil cihaz tarafından oluşturulan günlükleri kullanarak ek hata ayıklama yapmanız gerekebilir. Bu işlemler için Android Debug Bridge'e ihtiyacınız vardır.

Android Debug Bridge'i (ADB) kullanma

Devreye alma sorunlarını gidermenin bir diğer yolu da Android Debug Bridge (ADB) komut satırı aracını kullanmaktır. Devreye alma işlemi esas olarak mobil cihaz ile Matter cihaz arasında gerçekleştirildiğinden, devreye alma işlemi sırasında Google Home uygulaması tarafından oluşturulan günlüklere erişmek için ADB aracını kullanabilirsiniz.

Platform araçlarını yükleme

ADB, Android Studio ile veya sdkmanager komut satırı aracı aracılığıyla yüklenebilen Android SDK Platform Araçları'nın bir parçasıdır.

Platform araçlarını sisteminize başarıyla yükledikten sonra, aşağıdaki komutu kullanarak terminalde sürüm numarasını kontrol ederek ADB'yi doğrulayın:

$ adb -- version

Bu komut, yüklü ADB yardımcı programının sürüm numarasını hatasız olarak gösterir.

USB üzerinden hata ayıklamayı etkinleştirme

Ardından, Android cihazınızda USB hata ayıklama özelliğini etkinleştirin.

Öncelikle cihazınızda geliştirici seçeneklerini etkinleştirme adımlarını uygulayın, ardından USB hata ayıklamasını etkinleştirin.

Bu sayede ADB, cihazda çalışan uygulamalar tarafından oluşturulan günlüklere erişebilir.

Cihaz kimliğini alma

1. Aşağıdaki komutla ADB sunucusunu çalıştırın:

$ adb start-server

2. Telefonunuzu ADB sunucusunu çalıştıran bilgisayara bağlayın.

Telefonunuzda USB hata ayıklamayla ilgili bir uyarı mesajı görebilirsiniz. Bu mesajda, bilgisayarınızın telefonunuzdaki bilgilere erişmesine izin vermek isteyip istemediğiniz sorulur:

3. Bu uyarı mesajını alırsanız İzin ver'i tıklayın.
4. Bilgisayarınızın ADB üzerinden telefona erişip erişemediğini görmek için terminalden list devices komutunu verin:

$ adb devices

Bu işlem, şuna benzer bir yanıt verir:

List of devices attached
<phone-id>    device

<phone-id>, cihazınızı benzersiz şekilde tanımlayan bir alfanümerik dizedir.

5. Sonraki adımlarda kullanmak üzere <phone-id> değerini unutmayın.

Sistem bilgilerini toplama

Ardından, cihazınızdaki uygulamaların ve sistemin sürüm bilgilerini kontrol edin.

• Android OS sürümünü kontrol etmek için:

$ adb -s <phone-id> shell getprop ro.build.version.release

• Google Home uygulamasının sürümünü kontrol etmek için:

$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName

• Google Play Hizmetleri sürümünü kontrol etmek için:

$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"

• Play Hizmetleri üzerinden Home/Matter kontrol modüllerinin yüklü olup olmadığını kontrol etmek için:

$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"

Bu döndürülen değerlerin ekosistemimiz tarafından desteklendiğinden emin olun. Komisyon hataları konusunda destek almak için iletişime geçerken lütfen destek kaydınıza her zaman sistem bilgilerini ekleyin.

Hata günlüklerini toplama

Ardından, günlük toplama işlemini başlatın ve hata ayıklamak istediğiniz hata etkinliklerini oluşturmak için devreye alma adımlarını uygulayın.

1. <phone-id> değerinizi ve günlüklerin bilgisayarınızda kaydedileceği <file-name> değerini (ör. debug_file.txt).

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

Bu işlem, günlük kaydı sürecini hemen başlatır. Sağlanan ad henüz mevcut değilse bu ada sahip bir dosya oluşturulur ve her etkinlikten sonra telefondaki günlükler dosyaya eklenir.

Matter cihazınızla devreye alma adımlarına devam edin.

2. Hata ayıklama yapmak istediğiniz hataya ulaştığınızda, çalışan terminal penceresinde Control+C tuşuna basarak günlüğü durdurun.

Günlükleriniz artık <file-name> günlük kaydı dosyasında depolanıyor olmalıdır. Bu işlem, cihazda izlenen her çalışan işlemden günlük kaydedeceğinden bu dosyada çok fazla günlük bulunur. Bu nedenle, ihtiyacınız olan girişleri arayarak bu günlüklerden her zaman yararlanmanız gerekir.

Hata günlüklerini analiz etme

Devreye alma işlemleri, GHA'daki MatterCommissioner adlı bir alt sistem aracılığıyla yönetilir.

1. Devreye alma hataları analiz edilirken kullanılan ana stratejiyi uygulayarak aşağıdaki komutu kullanarak MatterCommissioner alt sistemi tarafından oluşturulan hataları arayın:

$ grep "MatterCommissioner" <file-name>

Bu işlem, devreye alma sürecindeki etkinlikleri içeren bir çıkış oluşturur.

2. Matter cihazınız Thread kullanıyorsa aşağıdaki komutla Thread alt sistemi tarafından oluşturulan hataları da arayabilirsiniz:

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

ADB hata ayıklama işlemi tarafından oluşturulan günlük dosyasını analiz ederken belirli kalıpları da arayın. Birçok devreye alma hatası, hata mesajında "commissioning failure" dizesini içerir.

3. Aşağıdaki komutu kullanarak devreye alma hatası mesajı arayın:

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

4. Cihaz Kontrolü Sorunlarını Ayıklama

Kullanıcılar, Matter cihazlarını kurar ve Google Home ekosisteminde kullanıma sunar. Ardından, Google Asistan'ı kullanarak (ör. "Ok Google, oturma odamdaki ışıkları aç") veya Home uygulamasındaki ya da Google Nest ekran cihazlarındaki kullanıcı arayüzünü kullanarak sesli komut verebilirler.

Uç cihazlar ile Google Hub'lar arasındaki kontrol spesifikasyonu Matter tarafından yönetildiğinden, cihaz kontrol tarafında daha az hata olması beklenir. Yine de bu tür sorunlarda hata ayıklamanız için metrikler ve günlükler sağlarız.

Metrikleri kullanma

Matter Entegrasyonu Kontrol Paneli'nde cihaz kontrolüyle ilgili çeşitli metrikler görürsünüz. Cihazlarınızın sahadaki performansını değerlendirmek için önemli olan üç grafik vardır:

Kontrol sorunları sırasında genellikle başarı yüzdesinde düşüş eğilimleri ve hata dökümü grafiğinde artış görürsünüz. Hata döküm grafiği, cihaz kontrol denemesinin neden başarısız olduğuyla ilgili olarak Google Nest Hub'ların yakaladığı hataları gösterir.

Günlükleri kullanma

Her Matter cihaz kontrol sorunu, sistemde bir hata günlüğü de oluşturur. Bu hatalar, Günlük Gezgini'nde "executionLog" aranarak filtrelenebilir.

Matter cihaz kontrol hata günlükleri aşağıdaki gibi görünür:

{
  "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"
}

Her hata günlüğü, zaman damgası, cihaz türü ve özelliğin yanı sıra statusType'teki kontrol isteğiyle ilişkili hatayı içerir. Çoğu kontrol hatası, hatanın neyle ilgili olduğunu açıklayan kısa bir hata mesajı olan externalDebugString öğesini de içerir.

5. Diğer özellikleri hata ayıklama

Şimdiye kadar Matter için cihaz devreye alma ve kontrol sorunlarını nasıl ele alacağınızı öğrendiniz. Ekosistemde, iyi kaliteli bir entegrasyon sağlamak için önerdiğimiz teknikleri kullanabileceğiniz başka özellikler de vardır.

OTA güncellemelerini izleme

Google Home tarafından yayınlanan Matter cihazlarına yönelik kablosuz (OTA) güncellemelerin sürümlerini takip etmek için, kullanımdaki cihazların donanım ve yazılım sürümlerini gösteren bir dizi metrik sağlarız.

Konsoldan güncelleme yayınladıktan sonra aşağıdaki metrikleri takip edin:

Sürümün yayınlanmasını takip eden günlerde, sahada bulunan daha fazla cihazın OTA yazılım sürümünüzle ilişkili yeni yazılım sürümünü aldığını göreceksiniz.

6. Destek alma

Google, Matter sorunlarınızı gidermeniz için araçlar ve dokümanlar sağlar. Ancak Matter ekosistemi yeni olduğu için bu kaynakların kapsamına girmeyen sorunlar olacaktır. Bu tür durumlarda destek almak için dilediğiniz zaman bize veya topluluğumuza ulaşabilirsiniz.

Geliştirici kanallarını ziyaret edin

Google'da aktif olarak izlenen üç geliştirici kanalı vardır:

Bu kanalların her biri aynı ekip tarafından düzenli olarak izlense de hangi kanalın ne zaman kullanılacağı konusunda bazı önemli farklılıklar vardır.

• Stack Overflow: Uygulamayla ilgili sorularınız veya yardım almak istediğiniz konular için bize ve Akıllı Ev geliştirici topluluğuna ulaşabilirsiniz. Bu kanal, sorunları nasıl gidereceğinizi veya belirli bir özelliği nasıl uygulayacağınızı öğrenmek için idealdir.
• Sorun Takip Aracı: Bu, Google tarafından yönetilen resmi sorun takip aracıdır. Harici kitlelerin ekosistemdeki hataları bildirebileceği bir platformdur. Gerektiğinde dosya eklemek ve hassas bilgileri paylaşmak için web araçları sağlar. Sorun İzleyici'yi kullanmak, ekosistemdeki sorunları bildirmek veya özellik isteklerini paylaşmak için en iyi yöntemdir.
• Geliştirici Forumu: Resmi Google destek ekibinden ve topluluk uzmanlarından yardım almak için Nest Geliştirici Forumu aracılığıyla iletişime geçebilirsiniz. Bu forum, geliştirmeyle ilgili resmi rehberlik almak için en iyi seçenektir.

Geliştirici bültenine kaydolun

Sorularınız için geliştirici kanallarını ziyaret edebileceğiniz gibi, yeni özellikleri öne çıkaran ve Google Akıllı Ev ekosisteminin durumuyla ilgili haberler sunan üç aylık bir bülten de yayınlayabilirsiniz.

Geliştirici bültenini almak için kayıt formunu kullanabilirsiniz.

7. Tebrikler

Tebrikler! Önerdiğimiz araçları ve teknikleri kullanarak Matter entegrasyonlarında nasıl hata ayıklayacağınızı başarıyla öğrendiniz. Google Home ile Matter entegrasyonlarını oluşturma konusunda iyi çalışmalar dileriz.

Sonraki adımlar

Aşağıdaki alıştırmaları deneyin ve ek kaynakları keşfedin:

• Sorunları gidermek için analizleri kullanmanın yanı sıra entegrasyonunuzu olası sorunlara karşı test etmek için Test Paketi'ni de kullanabilirsiniz.
• Entegrasyonunuz dünyayla paylaşılmaya hazır olduğunda, sonraki adım projenizin WWGH sertifikası almasıdır. Bunun için Sertifika sayfasındaki adımları uygulayabilirsiniz.