Konu Entegrasyonlarında Hata Ayıklama

1. Başlamadan önce

Matter, son kullanıcılara sorunsuz ve platformlar arası cihaz kurulumu ve kontrol deneyimi sunar. Bu durum, temel olarak arka planda birlikte çalışan birden fazla ekosistem bileşeni sayesinde mümkündür. Bu tür sorun giderme sistemleri yeni geliştiriciler için genellikle zorlayıcı olabilir. Bu nedenle, Google Home ile Matter geliştiricisi olarak hayatınızı kolaylaştıracak bir dizi araç ve teknik geliştirdik.

Bu codelab'de Matter ile ilgili üç ana bileşen ele alınmaktadır. Google, bu sistemlerin her biri için telefonlardan ve hub'lardan toplanan, geliştiricilere yönelik bir dizi sorun giderme analizi sağlar:

Geliştirici olarak, cihaz geliştirme döngüsü boyunca yaşadığınız sorunları azaltabilmeniz çok önemlidir. Projenizi başlattıktan sonra, sahada kullanılan cihazlardaki sorun trendlerini toplu olarak izlemeniz ve yazılım güncellemeleriyle düzeltmeniz gerekir. Bu codelab'de, bu amaçların her ikisi için de 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 telefonunuz olmalıdır (ADB günlükleri için).

Neler öğreneceksiniz?

• Matter sorunlarını büyük ölçekte izlemek için akıllı evle ilgili 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. Bu araçları kullanarak projenizin performansını ölçebilirsiniz.

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 önekiyle birlikte gelir.

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

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

Google Home kontrol panellerinde, projenizle ilişkili etkinliklerin ayrıntılarını gösteren çeşitli grafikler bulunur. 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 görürsünüz. Ayrıca Matter ile, devreye alma başarısını ve cihazlarınızdaki güncelleme kullanımlarını takip eden bir dizi grafiğe sahip olursunuz.

Google Home Analytics kontrol panellerinde gördüğünüz grafiklerin bulunduğu 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 erişebilirsiniz.

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

Gezgin penceresinde günlükleri görüntülemek, filtrelemek, sorgulamak ve analiz etmek için çeşitli araçlar bulunur. Bu görünüm, varsayılan olarak Smart Home dışında oluşturulan günlükler de dahil olmak üzere projenizde kullanılabilen tüm sistemlerden oluşturulan günlükleri gösterir. Bu nedenle, hata ayıklamak istediğiniz etkinlikleri filtreleyerek bu günlükleri kullanmanız önemlidir. Bu konuyu hata ayıklama bölümlerinde daha ayrıntılı olarak ele alacağız.

3. Devreye alma sorunlarında hata ayıklama

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

Cihaz devreye alma işlemi sırasında Matter cihazı, Google Home uygulaması ve Matter ağı 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ı ayıklamaya yönelik araç ve teknikler ele alınacaktır.

Google Home Analytics'i kullanma

Etkinlikleri izleyerek ve hataların hangi aşamada oluşabileceğini anlayarak komisyon sorunlarını araştırmanız için bir dizi metrik oluşturduk. Bunları, önceki bölümde ele aldığımız gibi Matter Entegrasyon Kontrol Paneli'nde bulabilirsiniz.

Bu kontrol panelindeki grafikler, cihaz devreye alma ile ilgili veriler sağlar:

Cihaz sayısı grafiğinde, belirli bir tarihte kullanıcılar tarafından yapılan devreye alma denemelerinin sayısı gösterilir. Başarı oranı, Google tarafında bu etkinliklerin algılanan başarı oranını gösterir. Her bir devreye alma girişimi, ilişkili durumları olan bir dizi etkinlik oluşturur. Bu durumlardan herhangi birinde hata oluştuğunda bu hata, hata dökümü grafiğinde de gösterilir.

Devreye alma durumları:

• 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. Yayınlama hatalarını filtrelemek için sorgu alanında "clientUpdateLog" ile birlikte "severity>=ERROR" ifadesini arayabilirsiniz.

Matter için devreye alma hata günlüğü şu şekilde 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 kodunun yanı sıra yakalanan hatanın zaman damgalarını ve hangi ürününüzün hataya neden olduğunu belirlemenizi sağlayan Matter ürün kimliğini içerir. Aynı devreye alma denemesinden oluşturulan günlükler kümesi bir sessionId paylaşır.

Google Home Analytics'teki metrikleri kullanarak sorunun hangi aşamada meydana gelebileceğine dair ilk fikri edinebilirsiniz. Cihaz devreye alma hatalarının temel nedenini bulmak için bazen devreye alma işleminde 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 temel olarak mobil cihaz ile Matter cihaz arasında yapıldığından, devreye alma işlemi boyunca Google Home uygulaması tarafından oluşturulan günlükleri görüntülemek için ADB aracını kullanabilirsiniz.

Platform araçlarını yükleme

ADB, Android SDK Platform Tools'un bir parçası olarak gelir. Bu araçlar, Android Studio ile veya sdkmanager komut satırı aracıyla yüklenebilir.

Platform araçlarını sisteminize başarıyla yükledikten sonra, terminalden aşağıdaki komutla 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 bir şekilde göstermelidir.

USB üzerinden hata ayıklamayı etkinleştirme

Ardından, Android cihazınızda USB üzerinden hata ayıklamayı etkinleştirin.

Öncelikle cihazınızda Geliştirici seçeneklerini etkinleştirme ve ardından USB üzerinden hata ayıklamayı etkinleştirme adımlarını uygulayın.

Bu, ADB'nin cihazda şu anda çalışan uygulamalar tarafından oluşturulan günlük dosyalarına erişmesine olanak tanır.

Cihaz kimliğini alma

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

$ adb start-server

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

Telefonunuzda USB üzerinden hata ayıklama ile ilgili bir uyarı mesajı alabilirsiniz. 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 aşağıdaki komutu kullanarak verin:

$ adb devices

Bu, şuna benzer bir yanıt verir:

List of devices attached
<phone-id>    device

<phone-id> öğesi, cihazınızı benzersiz şekilde tanımlayan alfanümerik bir 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 ev / Matter 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önüş değerlerinin ekosistemimiz tarafından desteklendiğinden emin olun. Devreye alma hatalarıyla ilgili destek almak için lütfen her zaman sistem bilgilerini destek bildirimlerinize ekleyin.

Hata günlüklerini toplama

Ardından, günlük toplama sürecini 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 <phone-id> değerinizi ve günlüklerin bilgisayarınızda kaydedileceği bir <file-name> (ör. sağlayarak çalıştırın: debug_file.txt).

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

Bu işlem, günlük kaydı sürecini hemen başlatır. Belirtilen ada sahip bir dosya yoksa oluşturulur ve her etkinlikten sonra telefondaki günlükler bu dosyaya eklenir.

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

2. Hata ayıklamak istediğiniz hataya ulaştığınızda ç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ına kaydedilmelidir. Bu işlem, cihazda izlenen her çalışan sürecin günlüklerini kaydettiğ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 yararlanmalısınız.

Hata günlüklerini analiz etme

Devreye alma işlemleri, GHA'daki MatterCommissioner adlı bir alt sistem üzerinden gerçekleştirilir.

1. Devreye alma hatalarını analiz ederken kullanılan ana stratejiyi izleyerek MatterCommissioner alt sistemi tarafından oluşturulan hataları aşağıdaki komutla arayın:

$ grep "MatterCommissioner" <file-name>

Bu işlem, devreye alma sürecindeki etkinlikleri içeren bir çıktı 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 yayınlama hatasının hata mesajında "commissioning failure" dizesi bulunur.

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

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

4. Cihaz kontrolü sorunlarında hata ayıklama

Kullanıcılar Matter cihazlarını Google Home ekosisteminde kurup devreye aldıktan sonra Google Asistan'ı kullanarak sesli komutlar verebilir (ör. "Ok Google, oturma odamdaki ışıkları aç") veya Home uygulamasındaki ya da Google Nest ekran cihazlarındaki kullanıcı arayüzünü kullanabilir.

Uç cihazlar ve Google Hub'lar arasındaki kontrol spesifikasyonu Matter tarafından sağlandığı için cihaz kontrolü tarafında daha az hata olması beklenir. Bununla birlikte, bu tür sorunları ayıklamanız için metrikler ve günlükler de sunuyoruz.

Metrikleri kullanma

Matter entegrasyonu kontrol panelinde, cihaz kontrolüyle ilgili çeşitli metrikler görürsünüz. Sahadaki cihazlarınızın performansını değerlendirmek için üç önemli grafik vardır:

Kontrol sorunları sırasında genellikle başarı yüzdesinde düşüş, hata dağılımı grafiğinde ise yükseliş görülür. Hata dökümü grafiği, cihaz kontrolü denemesinin neden başarısız olduğuna dair 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üğünde zaman damgası, cihaz türü ve özellik ile birlikte statusType içinde kontrol isteğiyle ilişkili hata yer alır. Birçok 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

Şimdiye kadar Matter'da cihazı kullanıma 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üncellemelerinin yayınlarını izlemek için, sahada bulunan cihazların donanım ve yazılım sürümlerini gösteren bir dizi metrik sunuyoruz.

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

Yayınlandıktan sonraki günlerde, sahada bulunan cihazların giderek artan bir kısmının OTA yazılım sürümünüzle ilişkili yeni yazılım sürümünü aldığını görürsünüz.

6. Destek Alma

Google, Matter sorunlarınızda hata ayıklamanıza yardımcı olacak araçlar ve dokümanlar sunar. Ancak Matter ekosistemi yeni olduğundan bu kaynakların kapsamadığı sorunlar olabilir. Bu gibi durumlarda destek almak için dilediğiniz zaman bize veya topluluğa ulaşabilirsiniz.

Geliştirici kanallarını ziyaret etme

Google'da etkin 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: Uygulama ile ilgili sorularınız veya rehberlik almak için bize ve Akıllı Ev geliştirici topluluğuna ulaşabilirsiniz. Bu kanal, sorunları giderme veya belirli bir özelliği uygulama hakkında soru sormak için en uygun kanaldır.
• Issue Tracker: Bu, Google tarafından yönetilen resmi sorun izleme sistemidir. Harici kitleler, ekosistemdeki hataları bu sistemde bildirebilir. Gerektiğinde dosya eklemek ve hassas bilgileri paylaşmak için web araçları sunar. Ekosistem sorunlarını bildirmek veya özellik isteklerini paylaşmak için en iyi yöntem Issue Tracker'ı kullanmaktır.
• Geliştirici Forumu: Resmi Google Destek Ekibi'nden ve topluluk uzmanlarından yardım almak için Nest Geliştirici Forumu'na ulaşabilirsiniz. Bu forum, \ geliştirme için resmi rehberlik almak üzere en uygun yerdir.

Geliştirici bültenine kaydolma

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 içeren üç 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ı oluştururken iyi vakit geçirmenizi 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 projenizi WWGH sertifikalı hale getirmektir. Bunun için Sertifika sayfasındaki adımları uygulayabilirsiniz.