Konu Entegrasyonlarında Hata Ayıklama

bookmark_border Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

1. Başlamadan önce

Matter, son kullanıcılara sorunsuz ve platformlar arası bir cihaz kurulumu ve kontrol deneyimi sunar. Bu, esas 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 kurulumu ile 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ı önceliklendirme.
• 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 çok önemlidir. 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 Ana Sayfa 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, ilgili 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.

Hata günlüklerine erişme

Günlük Gezgini, bir projede oluşturulan etkinlik günlükleriyle çalışmak için kullanılan bir araç koleksiyonudur. Google Cloud Console'da İşlemler > Günlük kaydı > Günlük Gezgini'ne giderek bu sayfaya erişebilirsiniz.

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, Akıllı Ev dışında oluşturulan günlükler de dahil olmak üzere projenizin erişebildiği tüm sistemlerden oluşturulan günlükler gösterilir. Bu nedenle, hata ayıklama yapmak istediğiniz etkinlikleri filtreleyerek bu günlükleri kullanmanız önemlidir. Bu konu, hata ayıklama bölümlerinde daha ayrıntılı olarak ele alınacaktır.

3. Devreye Alma Sorunlarında 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 adımları 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ını gidermek için kullanabileceğiniz araç ve teknikleri ele alacağız.

Google Home Analytics'i kullanma

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ı, Google'ın bu etkinliklerle ilgili 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 hata oluştuğunda hata dökümü grafiğinde de hata yakalanır.

Devreye alma eyaletleri:

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

Bu etkinliklerin ayrıntılı sürümünü görüntülemek için İşlemler > Günlük Kaydı > Günlük Gezgini'ne gidin. Devreye alma 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ı devreye alma denemesinden oluşturulan günlük grubu bir sessionId paylaşır.

Google Home Analytics'teki metrikleri kullanarak sorunun hangi aşamada ortaya çıkabileceğine dair ilk fikir edinebilirsiniz. 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 Tools'un 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. Devreye alma hatalarıyla ilgili destek almak için destek kayıtlarınıza lütfen 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 dosyasında depolanacaktır. Bu işlem, cihazda izlenen her çalışan işlemden günlük kaydedeceğinden bu dosyada çok sayıda 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 komutu kullanarak 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 Denetimi Sorunlarını Ayıklama

Kullanıcılar, Matter cihazlarını Google Home ekosisteminde kurup kullanıma aldıktan sonra 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 verebilir.

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. Bununla birlikte, bu tür sorunları da ayıklayabilmeniz için metrikler ve günlükler sunuyoruz.

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üşüş ve hata döküm grafiğinde artış eğilimi görürsünüz. Hata döküm grafiği, Google Nest Hub'ların cihaz kontrol denemesinin neden başarısız olduğuyla ilgili 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. Birçok denetim 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. Ayrıca, ekosistemde kullanabileceğiniz başka özellikler veya iyi kalitede bir entegrasyon sağlamak için önerilen teknikler 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 ele almadığı sorunlar olacaktır. Bu gibi durumlarda destek almak için dilediğiniz zaman bize veya topluluğa ulaşabilirsiniz.

Geliştirici kanallarını ziyaret edin

Google'da etkin bir şekilde 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, harici kitlelerin ekosistemdeki hataları bildirebileceği, Google tarafından yönetilen resmi sorun takip aracıdır. Gerektiğinde dosya eklemek ve hassas bilgileri paylaşmak için web araçları sağlar. Ekoloji sistemindeki sorunları bildirmek veya özellik isteklerini paylaşmak için Sorun Takip Aracı'nı kullanmak en iyi seçenektir.
• Geliştirici Forumu: Resmi Google destek ekibinden ve topluluk uzmanlarından yardım almak için Nest Geliştirici Forumu'na ulaşabilirsiniz. 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 etmenin yanı sıra, yeni özellikleri öne çıkaran ve Google Akıllı Ev ekosisteminin durumuyla ilgili haberleri sunan üç aylık bir bülten de yayınlıyoruz.

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ı inceleyin:

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