Debugowanie integracji Matter

1. Zanim zaczniesz

Standard Matter zapewnia użytkownikom płynną konfigurację i obsługę urządzeń na wielu platformach. Jest to możliwe głównie dzięki wielu komponentom ekosystemu, które działają ze sobą w tle. Rozwiązywanie problemów z takimi systemami może być trudne dla nowych deweloperów, dlatego opracowaliśmy szereg narzędzi i technik, które ułatwią Ci pracę jako deweloperowi Matter z Google Home.

W tym laboratorium kodowania omówimy 3 główne komponenty Matter. W przypadku każdego z tych systemów Google udostępnia programistom zestaw danych analitycznych do rozwiązywania problemów, które są zbierane z telefonów i hubów:

Jako deweloper musisz być w stanie rozwiązywać problemy, które napotykasz w trakcie cyklu tworzenia urządzenia. Po uruchomieniu projektu musisz monitorować trendy dotyczące problemów z urządzeniami w terenie w sposób zbiorczy i rozwiązywać je za pomocą aktualizacji oprogramowania. W tym samouczku znajdziesz techniki, które możesz wykorzystać w obu tych celach.

Wymagania wstępne

• Zapoznaj się z przewodnikiem Pierwsze kroki z Matter, w którym znajdziesz działający projekt Matter i konfigurację urządzenia.
• mieć telefon z Androidem, który można połączyć ze stacją roboczą (w celu uzyskania logów ADB);

Czego się nauczysz

• Jak używać narzędzi analitycznych do inteligentnego domu, aby monitorować problemy z Matter na dużą skalę.
• Jak klasyfikować błędy, uzyskując dostęp do dzienników błędów i zbierając informacje.
• Jak uzyskać dostęp do dokumentacji i materiałów pomocy dotyczących Matter, aby uzyskać pomoc.

2. Wyświetlanie statystyk Google Home

Monitorowanie wydajności ma kluczowe znaczenie dla udanej integracji z ekosystemem Google Home. Deweloperom inteligentnego domu udostępniamy zestaw narzędzi do monitorowania na Google Cloud Platform. Za pomocą tych narzędzi możesz mierzyć skuteczność projektu.

Dostęp do danych projektu

• Aby uzyskać dostęp do danych, najpierw sprawdź panele Google Home. W tym celu zaloguj się w konsoli Google Cloud i kliknij Operacje > Monitorowanie > Panele informacyjne.

W projekcie masz do dyspozycji kilka paneli (w tym innych usług GCP). Panele dotyczące inteligentnego domu mają prefiks Google Home Analytics.

Obecnie mamy ogólny panel, który obejmuje cały projekt, a także panele dla konkretnych integracji (Cloud, Local, Matter) lub typów urządzeń (kamery). Te panele zawierają dane tylko wtedy, gdy masz integrację odpowiedniego typu oraz działający projekt, który realizuje żądania.

Gdy otworzysz jeden z tych paneli, zobaczysz serię wykresów podobnych do tych:

Panele informacyjne Google Home zawierają różne wykresy, które pokazują szczegóły zdarzeń powiązanych z Twoim projektem. Na każdym panelu integracji znajdziesz wykres pokazujący łączną liczbę żądań obsługiwanych przez Twój projekt, wykres pokazujący odsetek udanych integracji danego typu oraz kilka wykresów pokazujących typy i cechy urządzeń. Dodatkowo w przypadku Matter masz do dyspozycji zestaw wykresów, które śledzą skuteczność wdrażania i wprowadzania aktualizacji na urządzeniach.

Pamiętaj, że widok domyślny z wykresami, które widzisz w panelach Google Home Analytics, to tylko widok utworzony przez nas na potrzeby Twojego projektu na podstawie danych o inteligentnym domu. Za pomocą narzędzia Metrics Explorer możesz też tworzyć własne wykresy na podstawie tych samych danych i zapisywać je w panelach niestandardowych.

Dostęp do logów błędów

Eksplorator logów to zbiór narzędzi do pracy z logami zdarzeń generowanymi w projekcie. Jest on dostępny w konsoli Google Cloud po kliknięciu Operacje > Logowanie > Eksplorator logów.

Po otwarciu eksploratora logów zobaczysz widok podobny do tego:

Okno eksploratora zawiera różne narzędzia do wyświetlania, filtrowania, wysyłania zapytań i analizowania logów. Domyślnie ten widok pokazuje logi wygenerowane przez wszystkie systemy dostępne dla Twojego projektu, w tym logi wygenerowane poza inteligentnym domem. Dlatego ważne jest, aby używać tych dzienników, filtrując zdarzenia, które chcesz debugować. Więcej informacji na ten temat znajdziesz w sekcjach dotyczących debugowania.

3. Debugowanie problemów z uruchamianiem

Pierwszy typ danych, któremu się przyjrzymy, dotyczy zdarzeń związanych z wdrażaniem Matter. Wprowadzanie do eksploatacji to zestaw czynności, które użytkownik musi wykonać, aby po raz pierwszy skonfigurować urządzenie Matter.

Podczas uruchamiania urządzenia dochodzi do szeregu interakcji między urządzeniem Matter, aplikacją Google Home i siecią Matter. Na ilustracji poniżej przedstawiono niektóre z tych zdarzeń:

Więcej informacji o każdym z tych kroków znajdziesz na stronie wprowadzającej w podstawowych informacjach o Matter. W tej sekcji omówimy narzędzia i techniki, które pomogą Ci rozwiązać problemy z wdrażaniem.

Korzystanie z Google Home Analytics

Utworzyliśmy zestaw danych, które pomogą Ci zbadać problemy z prowizjami. Możesz śledzić zdarzenia i sprawdzać, na jakim etapie mogą wystąpić błędy. Znajdziesz je w panelu integracji Matter, o czym pisaliśmy w poprzedniej sekcji.

Wykresy w tym panelu zawierają dane dotyczące wdrażania urządzeń:

Wykres liczby urządzeń pokazuje liczbę prób uruchomienia przez użytkowników w danym dniu. Wskaźnik sukcesu pokazuje szacowany wskaźnik sukcesu tych wydarzeń po stronie Google. Każda próba uruchomienia generuje zestaw zdarzeń z powiązanymi stanami. Gdy w którymś z tych stanów wystąpi błąd, zostanie on również zarejestrowany na wykresie podziału błędów.

Stany, w których obowiązuje program:

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

Aby wyświetlić szczegółową wersję tych zdarzeń, otwórz Operacje > Logowanie > Eksplorator logów. Aby filtrować błędy uruchomienia, możesz wyszukać w polu zapytania „clientUpdateLog” w połączeniu z „severity>=ERROR”.

Dziennik błędów dotyczących Matter wygląda tak:

{
  "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"
}

Oprócz stanu uruchomienia i kodu stanu dziennik błędów zawiera sygnatury czasowe zarejestrowanego błędu oraz identyfikator produktu Matter, który umożliwia określenie, który z Twoich produktów spowodował błąd. Zestaw logów wygenerowanych w ramach tej samej próby uruchomienia ma ten sam sessionId.

Korzystanie z danych z Google Home Analytics daje wstępne pojęcie o tym, na jakim etapie może wystąpić problem. Aby znaleźć główną przyczynę błędów podczas wdrażania urządzenia, czasami może być konieczne dodatkowe debugowanie przy użyciu logów wygenerowanych przez urządzenie mobilne użyte w procesie wdrażania. W tym celu musisz użyć Android Debug Bridge.

Korzystanie z narzędzia Android Debug Bridge (ADB)

Inny sposób na rozwiązywanie problemów z uruchamianiem to użycie narzędzia wiersza poleceń Android Debug Bridge (ADB). Proces wprowadzania urządzenia do eksploatacji odbywa się głównie między urządzeniem mobilnym a urządzeniem Matter, dlatego możesz użyć narzędzia ADB, aby uzyskać dostęp do logów generowanych przez aplikację Google Home podczas tego procesu.

Instalowanie narzędzi platformy

ADB jest częścią narzędzi platformy Android SDK, które można zainstalować za pomocą Androida Studio lub narzędzia wiersza poleceń sdkmanager.

Po zainstalowaniu narzędzi platformy w systemie sprawdź, czy ADB działa prawidłowo, wpisując w terminalu to polecenie:

$ adb -- version

Powinien wyświetlić numer wersji zainstalowanego narzędzia ADB bez żadnych błędów.

Włącz debugowanie USB

Następnie włącz debugowanie USB na urządzeniu z Androidem.

Najpierw wykonaj czynności, aby włączyć opcje programisty na urządzeniu, a potem włącz debugowanie USB.

Dzięki temu ADB może uzyskiwać dostęp do dzienników generowanych przez aplikacje działające obecnie na urządzeniu.

Pobieranie identyfikatora urządzenia

1. Uruchom serwer ADB za pomocą tego polecenia:

$ adb start-server

2. Podłącz telefon do komputera, na którym działa serwer ADB.

Na telefonie może pojawić się ostrzeżenie dotyczące debugowania USB z pytaniem, czy chcesz zezwolić komputerowi na dostęp do informacji z telefonu:

3. Jeśli zobaczysz ten komunikat z ostrzeżeniem, kliknij Zezwalaj.
4. Wydaj polecenie list devices w terminalu, aby sprawdzić, czy komputer ma dostęp do telefonu przez ADB. Użyj tego polecenia:

$ adb devices

Powinna wyświetlić się odpowiedź podobna do tej:

List of devices attached
<phone-id>    device

<phone-id> to ciąg alfanumeryczny, który jednoznacznie identyfikuje Twoje urządzenie.

5. Zapamiętaj wartość <phone-id>, aby użyć jej w następnych krokach.

Zbieranie informacji o systemie

Następnie sprawdź informacje o wersji aplikacji i systemu na urządzeniu.

• Aby sprawdzić wersję systemu operacyjnego Android:

$ adb -s <phone-id> shell getprop ro.build.version.release

• Aby sprawdzić wersję aplikacji Google Home:

$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName

• Aby sprawdzić wersję Usług Google Play:

$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"

• Aby sprawdzić, czy masz moduły sterowania domem lub standard Matter w Usługach Google Play:

$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"

Upewnij się, że te wartości zwracane są obsługiwane przez nasz ekosystem. Gdy kontaktujesz się z zespołem pomocy w sprawie nieudanych wdrożeń, zawsze podawaj w zgłoszeniach informacje o systemie.

Zbieranie logów błędów

Następnie rozpocznij proces zbierania logów i wykonaj czynności związane z uruchomieniem, aby wygenerować zdarzenia błędów, które chcesz debugować.

1. Uruchom to polecenie, podając swój <phone-id> oraz <file-name>, w którym dzienniki zostaną zapisane na komputerze (np. debug_file.txt).

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

Spowoduje to natychmiastowe rozpoczęcie procesu rejestrowania. Jeśli plik o podanej nazwie nie istnieje, zostanie utworzony, a po każdym zdarzeniu będą do niego dodawane dzienniki z telefonu.

Wykonaj czynności związane z uruchomieniem urządzenia Matter.

2. Gdy dotrzesz do błędu, który chcesz debugować, zatrzymaj rejestrowanie, naciskając Control+C w oknie działającego terminala.

Logi powinny być teraz przechowywane w pliku logowania <file-name>. Ponieważ ten proces rejestruje logi z każdego uruchomionego procesu śledzonego na urządzeniu, w tym pliku będzie dużo logów. Dlatego zawsze warto korzystać z tych dzienników, wyszukując potrzebne wpisy.

Analizowanie logów błędów

Procesy uruchamiania są obsługiwane przez podsystem o nazwie MatterCommissioner w ramach GHA.

1. Postępując zgodnie z główną strategią stosowaną podczas analizowania błędów związanych z uruchamianiem, poszukaj błędów wygenerowanych przez podsystem MatterCommissioner za pomocą tego polecenia:

$ grep "MatterCommissioner" <file-name>

Spowoduje to wygenerowanie danych wyjściowych zawierających zdarzenia z procesu uruchamiania.

2. Jeśli urządzenie Matter korzysta z technologii Thread, możesz też wyszukać błędy wygenerowane przez podsystem Thread za pomocą tego polecenia:

$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

Podczas analizowania pliku dziennika wygenerowanego przez proces debugowania ADB szukaj też określonych wzorców. Wiele błędów związanych z uruchomieniem zawiera w komunikacie o błędzie ciąg znaków „commissioning failure”.

3. Wyszukaj komunikat o niepowodzeniu wdrożenia za pomocą tego polecenia:

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

4. Debugowanie problemów ze sterowaniem urządzeniami

Gdy użytkownicy skonfigurują urządzenia Matter i dodadzą je do ekosystemu Google Home, będą mogli wydawać polecenia głosowe za pomocą Asystenta Google (np. „OK Google, włącz światło w salonie”) lub korzystać z interfejsu aplikacji Home albo ekranów Google Nest.

Specyfikacja sterowania między urządzeniami końcowymi a hubami Google jest pośredniczona przez Matter, więc po stronie sterowania urządzeniami powinno być mniej błędów. Niezależnie od tego udostępniamy dane i logi, które pomogą Ci rozwiązać tego typu problemy.

Używanie danych

W panelu integracji Matter zobaczysz kilka wskaźników dotyczących sterowania urządzeniami. Do oceny skuteczności urządzeń w terenie służą 3 wykresy:

W przypadku problemów z kontrolą zwykle obserwuje się tendencję spadkową w procentowym udziale udanych importów i tendencję wzrostową na wykresie zestawienia błędów. Wykres zestawienia błędów pokazuje błędy zarejestrowane przez Google Nest Hub dotyczące przyczyn niepowodzenia próby sterowania urządzeniami.

Korzystanie z logów

Każdy problem z kontrolą urządzenia obsługującego standard Matter generuje też w systemie dziennik błędów. Te błędy można odfiltrować w eksploratorze logów, wyszukując „executionLog”.

Dzienniki błędów sterowania urządzeniami Matter wyglądają tak:

{
  "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"
}

Każdy dziennik błędów zawiera sygnaturę czasową, typ urządzenia i cechę, a także błąd powiązany z żądaniem sterowania w statusType. Wiele błędów kontroli zawiera też externalDebugString, czyli krótki komunikat o błędzie, który wyjaśnia, czego dotyczy błąd.

5. Debugowanie innych funkcji

Wiesz już, jak rozwiązywać problemy z uruchamianiem i sterowaniem urządzeniami Matter. W ekosystemie są też inne funkcje, z których możesz korzystać, oraz zalecane techniki, które zapewnią dobrą jakość integracji.

Śledzenie aktualizacji OTA

Aby śledzić wersje aktualizacji OTA (Over-the-air) urządzeń Matter wydawane przez Google Home, udostępniamy zestaw danych, które pokazują wersje sprzętu i oprogramowania urządzeń w terenie.

Po wprowadzeniu aktualizacji w konsoli obserwuj te dane:

Zauważysz, że w dniach następujących po wydaniu aktualizacji coraz więcej urządzeń w terenie będzie otrzymywać nową wersję oprogramowania powiązaną z wydaną aktualizacją OTA.

6. Uzyskaj pomoc

Google udostępnia narzędzia i dokumentację, które pomogą Ci debugować problemy ze standardem Matter. Ekosystem standardu Matter jest jednak nowy, więc mogą wystąpić problemy, których te materiały nie obejmują. W takich przypadkach zawsze możesz skontaktować się z nami lub społecznością, aby uzyskać pomoc.

Odwiedź kanały dla programistów

W Google aktywnie monitorowane są 3 kanały dla deweloperów:

Chociaż każdy z tych kanałów jest okresowo monitorowany przez ten sam zespół, istnieją pewne kluczowe różnice w zakresie tego, kiedy należy używać którego z nich.

• Stack Overflow: możesz się z nami skontaktować i zadać pytania dotyczące implementacji lub poprosić o wskazówki społeczność deweloperów inteligentnego domu. Ten kanał jest najlepszy do zadawania pytań o rozwiązywanie problemów lub wdrażanie określonych funkcji.
• Issue Tracker: to oficjalny system śledzenia problemów prowadzony przez Google, w którym odbiorcy zewnętrzni mogą zgłaszać błędy w ekosystemie. Udostępnia narzędzia internetowe do dołączania plików i udostępniania informacji poufnych w razie potrzeby. Najlepszym sposobem na zgłaszanie problemów z ekosystemem lub udostępnianie próśb o dodanie funkcji jest korzystanie z Issue Trackera.
• Forum dla deweloperów: jeśli chcesz uzyskać pomoc od oficjalnego zespołu pomocy Google i ekspertów ze społeczności, możesz skontaktować się z nimi na Forum dla deweloperów Nest. To forum jest najlepszym miejscem, aby uzyskać oficjalne wskazówki dotyczące programowania.

Zapisz się na newsletter dla deweloperów

Oprócz odwiedzania kanałów dla deweloperów, na których można zadawać pytania, co kwartał publikujemy newsletter z informacjami o nowych funkcjach i stanie ekosystemu inteligentnego domu Google.

Aby otrzymywać newsletter dla deweloperów, możesz skorzystać z formularza rejestracji.

7. Gratulacje

Gratulacje! Udało Ci się nauczyć debugowania integracji Matter za pomocą zalecanych przez nas narzędzi i technik. Życzymy powodzenia w tworzeniu integracji Matter z Google Home.

Dalsze kroki

Wykonaj te ćwiczenia i zapoznaj się z dodatkowymi materiałami:

• Oprócz korzystania z analityki do rozwiązywania problemów możesz też używać Test Suite, aby testować integrację pod kątem potencjalnych problemów.
• Gdy integracja będzie gotowa do udostępnienia, kolejnym krokiem będzie uzyskanie certyfikatu WWGH dla projektu. Aby to zrobić, wykonaj czynności opisane na stronie Certyfikacja.