Matter Entegrasyonlarında Hata Ayıklama

1. Başlamadan önce

Matter, son kullanıcılar için sorunsuz bir platformlar arası cihaz kurulumu ve kontrol deneyimi sunar. Bunun başlıca nedeni, arka planda birbiriyle bağlantılı olarak çalışan birden çok ekosistem bileşeni olmasıdır. Bu tür sorun giderme sistemleri genelde yeni geliştiriciler için göz korkutucu olabilir. Bu nedenle, Google Home'u kullanarak Matter geliştiricisi olarak hayatınızı kolaylaştıracak bir dizi araç ve teknik geliştirdik.

Matter'ın bu codelab'de ele alınan üç ana bileşeni vardır. Google, bu sistemlerin her birinde telefonlar ve merkezlerden toplanan geliştiriciler için bir dizi sorun giderme analizi sağlar:

Geliştirici olarak, cihaz geliştirme döngüsü boyunca yaşadığınız sorunları azaltabilmeniz önemlidir. Projenizi başlattıktan sonra, sahadaki cihazlarla ilgili sorun trendlerini toplu olarak izlemeniz ve bu güncellemeleri yazılım güncellemeleriyle düzeltmeniz gerekir. Bu codelab'de bu amaçlardan 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 telefona sahip olmak (ADB günlükleri için)

Neler öğreneceksiniz?

• Matter sorunlarını geniş ölçekte izlemek için Akıllı Ev'e yönelik analiz araçları nasıl kullanılır?
• 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üle

Performansı izlemek, Google Home ekosistemiyle başarılı bir entegrasyon sağlamak için kritik öneme sahiptir. Google Cloud Platform'da akıllı ev geliştiricilerine bir dizi izleme aracı sunuyoruz. Bu araçlardan yararlanarak projenizin performansını ölçebilirsiniz.

Proje metriklerine erişme

• Verilerinize erişmenin ilk adımı, Google Cloud Console'a giriş yapıp İşlemler > İzleme > Gösterge Tabloları'na giderek Google Home kontrol panellerini kontrol etmektir.

Projenizde kullanabileceğiniz çeşitli gösterge tabloları (diğer GCP ürünleri dahil) bulunur. Akıllı ev için sağlanan kontrol panellerinde Google Home Analytics öneki bulunur.

Şu anda projenizin tamamını kapsayan genel bir kontrol paneli ve belirli entegrasyonlar (Cloud, Yerel, Matter) veya cihaz türleri (Kameralar) için kontrol panelleri sunuyoruz. Bu kontrol panelleri, yalnızca karşılık gelen türde bir entegrasyonun yanı sıra istekleri yerine getiren çalışan bir projeniz varsa veri içerir.

Bu kontrol panellerinden birini açtığınızda aşağıdakine benzer 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ı, ilgili entegrasyon türünün başarı oranını ve ilgili cihaz türlerini ve özellikleri gösteren bir grafik görürsünüz. Ayrıca, Matter sayesinde, komisyon vermenin başarılı olduğunu ve cihazlarınızda yapılan güncellemelerin kullanıma sunulduğunu bildiren bir dizi tablonuz olur.

Google Home Analytics kontrol panellerinde gördüğünüz grafiklerdeki 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 gösterge tablolarınıza 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 koleksiyondur. Bu araca, Google Cloud Console'da İşlemler > Günlük Kaydı > Günlük Gezgini'ne giderek erişebilirsiniz.

Günlük Gezgini'ni açtıktan sonra aşağıdakine benzer bir görünüm elde edersiniz:

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üm, Smart Home dışında oluşturulan günlükler de dahil olmak üzere projenizdeki tüm sistemlerden oluşturulan günlükleri gösterir. Bu nedenle, hata ayıklamak istediğiniz etkinlikleri filtreleyerek bu günlükleri kullanmak çok önemlidir. Hata ayıklama bölümlerinde bu konuyu daha ayrıntılı olarak ele alacağız.

3. Komisyon Sorunlarını Giderme

İnceleyeceğimiz ilk metrik türü, Matter komisyon oluşturma etkinlikleridir. Komisyon alma, kullanıcının Matter cihazını ilk kez ayarlaması için gereken adımlardır.

Cihaz kurulurken 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 için Matter Primer sayfasındaki Komisyon sayfasını inceleyebilirsiniz. Bu bölümde, komisyonlama hatalarını ayıklamaya yönelik araçları ve teknikleri ele alacağız.

Google Home Analytics kullanın

Etkinlikleri izleyerek ve hataların hangi aşamada meydana gelebileceğini inceleyerek, komisyon durumlarını incelemeniz için bir dizi metrik oluşturduk. Bunları, önceki bölümde açıkladığımız gibi Matter Entegrasyon Kontrol Paneli'nde bulabilirsiniz.

Bu kontrol panelindeki grafikler, cihaz komisyonuyla ilgili veriler sağlar:

Cihaz sayısı grafiği, belirli bir tarihte kullanıcıların deneme yapma sayısını gösterir. Başarı oranı, Google tarafından bu etkinliklerin algılanan başarı oranını gösterir. Her deneme girişimi, ilişkili durumlara sahip bir dizi etkinlik oluşturur. Bu durumlardan birinde hata olduğunda, hata dökümü grafiğinde de yakalanır.

Komisyonun Bulunduğu Eyaletler:

• KOMİSYON_BAŞLANGIÇ
• ONBOARDING_PAYLOAD_GENERATED
• YEREL_DISCOVERY_BAŞARILI
• PASE_BAĞLANTISI_BAŞARILI
• NOC_ADDED_SUCCESSFULLY
• KOMİSYON_TAMAMLANDI

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. Komisyon hatalarını filtrelemek için sorgu alanında "clientUpdateLog" ile birlikte "severity>=ERROR" araması yapabilirsiniz.

Matter için hata ayıklama 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ük kaydı, durum durumuna ve durum koduna ek olarak, yakalanan hataya ait zaman damgalarının yanı sıra Matter Product ID'yi içerir. Böylece, hangi ürünlerinizin hataya neden olduğunu belirleyebilirsiniz. Aynı komisyon girişiminden oluşturulan günlük kümesi bir sessionId paylaşır.

Google Home Analytics'teki metrikleri kullanmak, sorunun hangi aşamada ortaya çıkabileceğine dair ilk fikir verir. Cihaz komisyonlama hatalarının temel nedenini bulmak için bazen komisyon işleminde kullanılan mobil cihaz tarafından oluşturulan günlükleri kullanarak ek hata ayıklama işlemleri yapmanız gerekebilir. Bunlar için Android Debug Bridge'e ihtiyacınız vardır.

Android Debug Bridge'i (ADB) kullanma

Komisyon teklifleriyle ilgili sorunları gidermenin başka bir yolu da Android Debug Bridge (ADB) komut satırı aracını kullanmaktır. Komisyonlama işlemleri çoğunlukla mobil cihaz ile Matter cihaz arasında yapıldığından, Google Home uygulaması tarafından oluşturulan günlüklere erişim için ADB aracını kullanmak mümkündür.

Platform araçlarını yükleme

ADB, Android Studio veya sdkmanager komut satırı aracı üzerinden 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 terminaldeki sürüm numarasını aşağıdaki komutla kontrol ederek ADB'yi doğrulayın:

$ adb -- version

Yüklenen ADB yardımcı programının sürüm numarası hata olmadan görüntülenir.

USB üzerinden hata ayıklamayı etkinleştir

Sonraki adım, Android cihazınızda USB üzerinden hata ayıklamayı etkinleştirmektir.

Ö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. ADB sunucusunu aşağıdaki komutla çalıştırın:

$ adb start-server

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

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

$ adb devices

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

List of devices attached
<phone-id>    device

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

5. Sonraki adımlarda kullanılması için <phone-id> değerini unutmayın.

Sistem bilgilerini toplama

Sonraki adım, cihazınızdaki uygulamaların ve sistemin sürüm bilgilerini kontrol etmektir.

• 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 üzerinden Ev / Madde 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 iade değerlerinin ekosistemi tarafından desteklendiğinden emin olun. Komisyon alma işlemleriyle ilgili destek ekibiyle iletişime geçerken lütfen destek kayıtlarınıza 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 ilk adımları uygulayın.

1. Aşağıdaki komutu çalıştırarak <phone-id> dosyanızı ve günlüklerin bilgisayarınızda saklanacağı bir <file-name> sağlayın (ör. debug_file.txt) seçebilirsiniz.

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

Bunu yaptığınızda günlük kaydı işlemi hemen başlar. Sağlanan ad, zaten mevcut değilse bir dosya oluşturulur ve telefondaki günlükler her etkinlikten sonra dosyaya eklenir.

Matter cihazınızla komisyon adımlarını uygulayın.

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

Günlükleriniz artık <file-name> günlük kaydı dosyasında depolanır. Bu işlem, cihazda izlenen her çalışan işlemin günlüklerini kaydettiğinden, bu dosyada çok fazla günlük olacaktır. Bu nedenle, ihtiyacınız olan girişleri arayarak bu günlükleri her zaman kullanmanız gerekir.

Hata günlüklerini analiz etme

Komisyon süreçleri, GHA'daki MatterCommissioner adlı bir alt sistem üzerinden gerçekleştirilir.

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

$ grep "MatterCommissioner" <file-name>

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

2. Matter cihazınızda Thread kullanılıyorsa şu komut aracılığıyla 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 olup olmadığına da bakın. Hata mesajında "commissioning failure" dizesini dahil eden çok sayıda hata bulunuyor.

3. Şu komutla, bir komisyon hata mesajı arayın:

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

4. Cihaz Kontrol Sorunlarında Hata Ayıklama

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

Son cihazlar ile Google Hub'lar arasındaki kontrol spesifikasyonu Matter tarafından uyumlu hale getirildiğinden, cihaz kontrol tarafında daha az hata olması beklenir. Ayrıca, bu tür sorunları gidermeniz için size metrikler ve günlükler de sağlarız.

Metrikleri kullanma

Matter Entegrasyon Kontrol Paneli'nde, cihaz kontrolüyle ilgili birkaç metrik görürsünüz. Cihazlarınızın sahadaki performansını değerlendirmek için kritik olan üç grafik vardır:

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

Günlükleri kullanma

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

Matter cihaz denetimi 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 içindeki kontrol isteğiyle ilişkili hatayı içerir. Çoğu kontrol hatasına, hatanın neyle ilgili olduğunu açıklayan kısa bir hata mesajı olan externalDebugString da dahildir.

5. Diğer Özelliklerde Hata Ayıklama

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

OTA güncellemelerini izleme

Google Home tarafından yayınlanan Matter cihazlarında kablosuz olarak (OTA) yapılan güncellemeleri izlemek için sahadaki cihazların donanım ve yazılım sürümlerini gösteren bir dizi metrik sağlarız.

Konsol üzerinden bir güncelleme yaptıktan sonra aşağıdaki metrikleri takip edin:

Yayından sonraki günlerde, OTA yazılım sürümünüzle ilişkili yeni yazılım sürümünün sahada giderek daha fazla cihazda kullanıldığını göreceksiniz.

6. Destek Alın

Google, Matter sorunlarınızı ayıklamanız için araçlar ve dokümanlar sağlar. Matter ekosistemi yeni olduğundan bu kaynakların kapsamadığı sorunlar olacaktır. Bu gibi durumlarda, destek almak için her zaman bize veya topluluğa 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 aralıklarla izlenir ancak bunlardan hangisinin ne zaman kullanılacağıyla ilgili bazı önemli farklılıklar vardır.

• Stack Overflow: Uygulamayla ilgili sorularınızı sormak veya rehberlik almak için bize ve Smart Home geliştirici topluluğuna ulaşabilirsiniz. Bu kanal, sorunları nasıl gidereceğinizi veya belirli bir özelliği nasıl uygulayacağınızı sormak için en iyi seçenektir.
• Sorun İzleyici: Bu, harici kitlelerin ekosistemdeki hataları raporlayabildiği, Google tarafından işletilen resmi sorun izleme sistemidir. Dosya eklemek ve gerektiğinde 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 desteğinden ve topluluk uzmanlarından yardım almak için Nest Geliştirici Forumu üzerinden bize ulaşabilirsiniz. Bu forum, geliştirmeyle ilgili resmi yardım almak için idealdir.

Geliştirici bültenine kaydolun

Geliştirici kanallarını soru sormanın yanı sıra, yeni özellikleri öne çıkaran ve Google Akıllı Ev ekosisteminin durumuyla ilgili haberleri üç ayda bir sunan bir bülten yayınladık.

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

7. Tebrikler

Tebrikler! Önerdiğimiz araçları ve teknikleri kullanarak Matter entegrasyonlarında hata ayıklamayı başarıyla öğrendiniz. Google Home ile Matter entegrasyonlarını oluşturmak için iyi bir zaman diliyoruz.

Sonraki adımlar

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

• Sorunları gidermek için analiz kullanmanın yanı sıra entegrasyonunuzu olası sorunlara karşı test etmek amacıyla Test Paketi'ni de kullanabilirsiniz.
• Entegrasyonunuz dünyayla paylaşılmaya hazır olduğunda atacağınız bir sonraki adım, WWGH Sertifikalı projenizi kullanmaktır. Bunun için Sertifikalar sayfasındaki adımları uygulayabilirsiniz.