Konu Entegrasyonlarında Hata Ayıklama

1. Başlamadan önce

Matter, son kullanıcılar için 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, sahadaki cihazlarla ilgili sorun trendlerini toplu olarak izlemeniz ve yazılım güncellemeleri aracılığıyla 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ı evde 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 > Gösterge Tabloları'na giderek Google Home kontrol panellerini kontrol etmektir.

Projeniz için (diğer GCP ürünleri dahil) çeşitli kontrol panelleri mevcuttur. Akıllı ev için sağlanan kontrol panelleri Google Home Analytics önekini içerir.

Ş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 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 yer alır. Ayrıca Matter ile, devreye alma başarısının yanı sıra 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. Ayrıca, aynı temel metriklerden kendi grafiklerinizi oluşturmak ve bunları özel kontrol panellerinize kaydetmek için Metrik Gezgini'ni 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'ın kullanıma alma etkinlikleriyle ilgilidir. Devreye alma, kullanıcının ilk kez bir Matter cihazı 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ı, bu etkinliklerin Google tarafındaki algılanan başarı oranını gösterir. Her 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 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 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 Araçları'nın 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 komutu kullanarak 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üklerine 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 aşağıdaki komutu kullanarak list devices komutunu verin:

$ adb devices

Bu, şuna benzer bir yanıt verir:

List of devices attached
<phone-id>    device

<phone-id>, 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 destek bildirimlerinize her zaman sistem bilgilerini 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. <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. 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 işlemin 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. Komisyon verme 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 çı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 yayınlama hatasının hata mesajında "commissioning failure" dizesi yer alır.

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ığından 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. Cihazlarınızın sahadaki 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çindeki 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 ile ilgili 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 verilen Matter cihazlarına yönelik kablosuz (OTA) güncellemelerinin yayınlarını takip etmek için, sahada kullanılan 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 daha fazlası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ız için 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 izlenirken 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. Gerekli olduğunda 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.