Konu Entegrasyonlarında Hata Ayıklama

1. Başlamadan önce

Matter, son kullanıcılar için platformlar arası sorunsuz bir kurulum ve kontrol deneyimi sunar. Bunun nedeni, perde arkasında birbiriyle bağlantılı çalışan birden çok ekosistem bileşeninin bulunmasıdır. Bunun gibi sorun giderme sistemleri, yeni geliştiriciler için genellikle ürkütücü 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.

Bu codelab'de Matter'ın üç ana bileşeni ele alınmıştır. Google, bu sistemlerin her biri için telefon ve merkezlerden toplanan geliştiricilere yönelik bir dizi sorun giderme analizi sağlar:

Devreye Alma, Yürütme, OTA Güncellemesi

Geliştirici olarak, cihaz geliştirme döngüsü boyunca karşılaştığınız sorunları azaltabilmeniz çok önemlidir. Projenizi lanse ettikten sonra sahadaki cihazlarla ilgili sorun trendlerini toplu olarak takip etmeniz ve yazılım güncellemeleriyle bu sorunları düzeltmeniz gerekir. Bu codelab'de, bu iki amaç için kullanabileceğiniz teknikler ele alınmaktadır.

Ö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 telefona sahip olun (ADB günlükleri için)

Neler öğreneceksiniz?

  • Matter sorunlarını geniş ölçekte izlemek için Akıllı Ev'deki analiz araçlarını kullanma.
  • Hata günlüklerine erişip 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üle

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

Proje metriklerine erişme

  • Verilerinize erişmenin 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 birçok kontrol paneli vardır (diğer GCP ürünleri dahil). Akıllı ev için sağlanan kontrol panellerinde Google Home Analytics öneki bulunur.

Google Home Analytics kontrol panelleri

Ş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 var. Bu kontrol panellerinde yalnızca karşılık gelen türde bir entegrasyonunuz varsa ve istekleri yerine getiren çalışan bir proje varsa veriler yer alır.

Bu kontrol panellerinden birini açtığınızda, aşağıdakine benzeyen bir dizi grafik görürsünüz:

Başarı Oranı, Gecikme ve Cihaz Türü Dökümleri

Google Home kontrol panellerinde projenizle ilişkili etkinliklerin ayrıntılarını gösteren çeşitli grafikler bulunur. Her entegrasyon kontrol panelinde, projenizin ele aldığı 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ürleri ile özellikleri gösteren birkaç grafik görürsünüz. Buna ek olarak, Matter'da testin başarısını ve cihazlarınızdaki güncellemelerin kullanıma sunulmasını izlemek için bir dizi grafik kullanabilirsiniz.

Google Home Analytics kontrol panellerinde gördüğünüz grafiklerin yer aldığı varsayılan görünümün, akıllı ev metrik 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 olay günlükleriyle çalışan bir araç koleksiyonudur. Bu dosyaya Google Cloud Console'daki İşlemler > Günlük Kaydı > Günlük Gezgini bölümünden erişebilirsiniz.

Günlük Gezgini'ni açtığınızda aşağıdakine benzer bir görünümle karşılaşırsınız:

Günlük gezgini

Gezgin penceresi, günlükleri görüntülemek, filtrelemek, sorgulamak ve analiz etmek için çeşitli araçlar içerir. Varsayılan olarak bu görünümde, Akıllı Ev dışında oluşturulan günlükler de dahil olmak üzere projenizde kullanılabilen tüm sistemlerden oluşturulan günlükler gösterilir. Bu nedenle, hata ayıklamak istediğiniz etkinliklere göre filtre uygulayarak bu günlükleri kullanmanız çok ö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 için görevlendirme etkinlikleri ile 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 yapısı arasında bir dizi etkileşim gerçekleşir. Aşağıdaki resimde bu etkinliklerden bazıları gösterilmektedir:

Matter devreye alma etkinlikleri

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

Google Home Analytics'i kullanın

Etkinlikleri takip edip hataların hangi aşamada ortaya çıkabileceğini anlayarak devreye alma sorunlarını araştırmanız için bir dizi metrik oluşturduk. Bunları, bir önceki bölümde belirttiğimiz gibi Matter Integration (Konu Entegrasyonu Kontrol Paneli) bölümünde bulabilirsiniz.

Bu kontrol panelindeki grafikler, cihazın kullanıma sunulmasıyla ilgili veriler sağlar:

Cihaz komisyonu metrikleri

Cihaz sayısı grafiğinde, belirli bir tarihte kullanıcıların yaptığı kullanıma sunma denemelerinin sayısı gösterilir. Başarı oranı, Google tarafında bu etkinliklerin algılanan başarı oranını gösterir. Her devreye alma girişimi, ilişkili durumları içeren bir etkinlik grubu oluşturur. Bu durumlardan herhangi birinde hata oluşursa bu, hata dökümü grafiğinde de yakalanır.

Devreye Alınan Eyaletler:

  • 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 "severity>=ERROR" ile birlikte "clientUpdateLog" araması yapabilirsiniz.

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 durumu ve durum koduna ek olarak, yakalanan hata için zaman damgalarının yanı sıra hataya hangi ürünlerinizin neden olduğunu belirlemenize olanak tanıyan Matter Ürün Kimliği'ni içerir. Aynı devreye alma denemesinden oluşturulan günlük grubu bir sessionId değerini paylaşır.

Google Home Analytics metriklerini kullanmak, sorunun hangi aşamada ortaya çıkabileceğine dair ilk fikir edinmenize olanak tanır. Bazen devreye alma sırasında ortaya çıkan hataların temel nedenini bulmak için bazen, devreye alma işleminde kullanılan mobil cihaz tarafından oluşturulan günlüklerden yararlanarak ek hata ayıklama işlemleri yapmanız gerekebilir. Bunlar için Android Debug Bridge'e ihtiyacınız var.

Android Debug Bridge'i (ADB) kullanma

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

Platform araçlarını yükleme

ADB, Android SDK Platform Araçları'nın bir parçası olarak sunulur. Android Studio ile veya sdkmanager komut satırı aracı üzerinden yüklenebilir.

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

$ adb -- version

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

USB üzerinden hata ayıklamayı etkinleştir

Ardından, Android cihazınızda USB üzerinden hata ayıklamayı 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, ADB'nin o anda cihazda çalışan uygulamalar tarafından oluşturulan günlüklere erişmesine olanak tanır.

Cihaz kimliğini al

  1. ADB sunucusunu aşağıdaki komutla çalıştırın:
$ adb start-server
  1. Telefonunuzu ADB sunucusunu çalıştıran bilgisayara bağlayın.

Telefonunuzda, bilgisayarınızın telefonunuzdaki bilgilere erişmesine izin vermek isteyip istemediğinizi soran, USB hata ayıklamayla ilgili bir uyarı mesajı alabilirsiniz:

USB hata ayıklama istemi

  1. Bu uyarı mesajını alırsanız İzin ver'i tıklayın.
  2. Bilgisayarınızın ADB üzerinden telefona erişip erişemediğini görmek için aşağıdaki komutu kullanarak terminalden bir cihazları listeleme komutu verin:
$ adb devices

Bu, aşağıdakine benzer bir yanıt verecektir:

List of devices attached
<phone-id>    device

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

  1. Sonraki adımlarda kullanmak için <phone-id> değerini unutmayın.

Sistem bilgilerini toplama

Daha sonra, uygulamaların ve cihazınızdaki 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ı 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'nden Ev / Konu kontrol modüllerine sahip olup olmadığınızı 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ı ile ilgili destek almak istediğinizde lütfen destek kayıtları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. Aşağıdaki komutu çalıştırarak <phone-id> ve günlüklerin bilgisayarınızda kaydedileceği <file-name> dosyasını girin (ör. debug_file.txt).
$ adb -s <phone-id> logcat > <file-name>

Bu işlem hemen günlük kaydı işlemini başlatır. Dosya yoksa, sağlanan ada sahip bir dosya oluşturulur ve her etkinlikten sonra telefondaki günlükler dosyaya eklenir.

Matter cihazınızı kullanarak kullanıma sunmaya yönelik adımlara geçin.

  1. Hata ayıklamak istediğiniz hatayı gördüğünüzde çalışan terminal penceresinde Control+C tuşuna basarak günlük kaydını durdurun.

Günlükleriniz artık <file-name> günlük dosyasında depolanmaktadır. Bu işlem, cihazda izlenen her çalışan işleme ait günlükleri kaydettiğinden, bu dosyada çok sayıda günlük olacaktır. Bu nedenle, ihtiyacınız olan girişleri arayarak bu günlükleri her zaman kullanmalısınız.

Hata günlüklerini analiz etme

Devreye alma süreçleri, GHA içindeki MatterCommissioner adlı bir alt sistem üzerinden yürütülür.

  1. Devreye alma hatalarını analiz ederken kullanılan ana stratejinin ardından, aşağıdaki komutla 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 çıktı oluşturur.

  1. Matter cihazınız iş parçacığı 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. Devreye alma hatalarının çoğu hata mesajında "commissioning failure" dizesini içerir.

  1. Aşağıdaki komutu kullanarak devreye alma hata mesajını arayın:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"

4. Cihaz Denetimi Sorunlarında Hata Ayıklayın

Kullanıcılar Matter cihazlarını kurup Google Home ekosistemine dahil ettikten sonra Google Asistan'ı (ör. "Ok Google, salonumdaki ışıkları aç") ya da Home uygulamasındaki veya Google Nest ekran cihazlarındaki kullanıcı arayüzünü kullanarak sesli komut verebilirler.

Son cihazlar ile Google Hub'lar arasındaki kontrol spesifikasyonu Matter ile uyumlulaştırıldığından, cihaz kontrol tarafında daha az hata olması beklenmektedir. Yine de bu tür sorunları gidermeniz 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. Sahada cihazlarınızın performansını değerlendirmek için kritik öneme sahip üç grafik vardır:

Başarı, gecikme ve hata dökümü grafikleri

Kontrol sorunları sırasında genellikle başarı yüzdesinde düşüş trendleri 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 Hubs tarafından yakalanan hataları gösterir.

Günlükleri kullanma

Her Matter cihaz kontrolü sorunu, sistemde bir hata günlüğü oluşturur. Bu hatalar "executionLog" araması yapılarak Günlük Gezgini'nde 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üğü bir zaman damgası, cihaz türü ve özelliğin yanı sıra statusType içindeki 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 içerir.

5. Diğer Özelliklerde Hata Ayıklama

Şu ana kadar Matter ile ilgili cihazları devreye alma ve kontrol etme sorunlarını nasıl ele alacağınızı öğrendiniz. Ekosistem içinde, kaliteli bir entegrasyon sağlamak için önerilen tekniklerimizi kullanabileceğiniz başka özellikler de vardır.

OTA güncellemelerini takip etme

Google Home tarafından yayınlanan Matter cihazların kablosuz (OTA) güncellemelerinin sürümlerini takip etmek için sahadaki cihazların donanım ve yazılım sürümlerini gösteren bir dizi metrik sağlıyoruz.

Konsoldan bir güncelleme yayınladığınızda, aşağıdaki metriklere dikkat edin:

Yazılım ve Donanım dökümleri

Oyunun kullanıma sunulmasından sonraki günlerde, sahada giderek 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ı ayıklamanız için araçlar ve belgeler sağlar. Bununla birlikte, Matter ekosistemi yeni olduğundan bu kaynakların kapsamadığı sorunlar olacaktır. Bu durumlarda destek almak için bize veya topluluğa her zaman ulaşabilirsiniz.

Geliştirici kanallarını ziyaret edin

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

Stack Overflow, Sorun İzleyici, Geliştirici Forumu

Bu kanalların her biri aynı ekip tarafından düzenli olarak izlenmekle birlikte, hangi kanalın ne zaman kullanılacağı konusunda bazı önemli farklılıklar söz konusudur.

  • Stack Overflow: Uygulamayla ilgili sorularınız olursa veya yardım almak isterseniz bize ve Akıllı Ev geliştirici topluluğuna ulaşabilirsiniz. Bu kanal, sorunların nasıl giderileceğini veya belirli bir özelliğin nasıl uygulanacağını sormak için idealdir.
  • Sorun İzleyici: Bu, harici kitlelerin ekosistemdeki hataları bildirebileceği, Google tarafından işletilen resmi sorun izleyici sistemidir. Gerektiğinde dosya eklemek ve hassas bilgileri paylaşmak için web araçları sağlar. Sorun İzleyici'yi kullanmak, ekosistem sorunlarını bildirmek veya özellik isteklerini paylaşmak için en iyi seçenektir.
  • Geliştirici Forumu: Resmi Google Destek Ekibi ve topluluk uzmanlarından yardım almak için Nest Geliştirici Forumu üzerinden iletişime geçebilirsiniz. Bu forum, geliştirmeyle ilgili resmi yardım almak için idealdir.

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 bültenler de yayınlıyoruz.

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

7. Tebrikler

Google Home

Tebrikler! Önerdiğimiz araçları ve teknikleri kullanarak Matter entegrasyonlarında hata ayıklamayı başarıyla öğrendiniz. Google Home ile Matter entegrasyonları derlediğiniz 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 bir sonraki adım, projenizin WWGH Sertifikalı olmasını sağlamaktır. Bunun için Sertifika sayfasındaki adımları uygulayabilirsiniz.