Debugowanie integracji Matter

1. Zanim zaczniesz

Matter umożliwia użytkownikom bezproblemową, wieloplatformową konfigurację urządzeń i kontrolę. Jest to możliwe głównie dzięki wielu komponentom ekosystemu, które współdziałają ze sobą. Rozwiązywanie problemów z takimi systemami może być zniechęcające dla nowych deweloperów, dlatego opracowaliśmy serię narzędzi i technik, które ułatwią Ci życie jako programista Matter na Google Home.

W tym ćwiczeniu z programowania opisujemy 3 główne komponenty standardu Matter. W przypadku każdego z tych systemów Google zapewnia deweloperom zestaw danych analitycznych dotyczących rozwiązywania problemów zebranych z telefonów i centrów:

Deweloper musi być w stanie rozwiązywać problemy, które pojawiają się na każdym etapie cyklu tworzenia urządzenia. Po uruchomieniu projektu musisz zbiorczo monitorować trendy występowania problemów z urządzeniami w terenie i naprawiać je za pomocą aktualizacji oprogramowania. W tym ćwiczeniu z programowania omawiamy techniki, których możesz używać do obu tych celów.

Wymagania wstępne

• Ukończ przewodnik na temat rozpoczynania pracy ze standardem Matter, dodając działający projekt i konfigurację urządzenia w standardzie Matter
• mieć telefon z Androidem, który możesz połączyć ze swoją stacją roboczą (na potrzeby dzienników ADB)

Czego się nauczysz

• Jak używać narzędzi analitycznych w inteligentnym domu do monitorowania problemów 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 Matter i zasobów pomocy w celu uzyskania pomocy.

2. Wyświetlanie Statystyk Google Home

Monitorowanie wydajności ma kluczowe znaczenie dla udanej integracji z ekosystemem Google Home. Programistom inteligentnych domów udostępniamy zestaw narzędzi do monitorowania w Google Cloud Platform. Za pomocą tych narzędzi możesz mierzyć wydajność projektu.

Dostęp do wskaźników projektu

• Pierwszym krokiem, aby uzyskać dostęp do swoich danych, jest sprawdzenie paneli Google Home. Aby to zrobić, zaloguj się w Google Cloud Console i kliknij Operacje > Monitorowanie > Panele.

W ramach Twojego projektu dostępne są różne panele informacyjne (w tym inne usługi GCP). Panele przeznaczone do inteligentnego domu mają prefiks Google Home Analytics.

Obecnie dysponujemy ogólnym panelem obejmującym cały projekt, a także panele do konkretnej integracji (Cloud, Local, Matter) lub typów urządzeń (Aparaty). Zawierają one dane tylko wtedy, gdy masz integrację odpowiedniego typu oraz działający projekt, który spełnia żądania.

Po otwarciu jednego z tych paneli zobaczysz serię wykresów, które będą wyglądały tak:

Panele Google Home zawierają różne wykresy, które pokazują szczegóły zdarzeń powiązanych z Twoim projektem. W każdym panelu integracji znajdziesz wykres przedstawiający łączną liczbę żądań obsłużonych przez Twój projekt, wykres pokazujący wskaźnik sukcesu dotyczący danego typu integracji oraz kilka wykresów przedstawiających typy urządzeń i cechy, które są związane z tym procesem. Poza tym standard Matter udostępnia zestaw wykresów, na których można śledzić pomyślne rozpoczęcie realizacji zamówienia oraz informacje o wdrożeniach aktualizacji na urządzeniach.

Pamiętaj, że domyślny widok z wykresami widocznymi w panelach Analytics w Google Home to tylko widok, który utworzyliśmy dla Twojego projektu na podstawie danych z pomiarów inteligentnego domu. Za pomocą narzędzia Metrics Explorer możesz też tworzyć własne wykresy na podstawie tych samych podstawowych danych i zapisywać je w panelach niestandardowych.

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

Eksplorator logów to zbiór narzędzi do pracy z logami zdarzeń wygenerowanymi w projekcie. Jest on dostępny w konsoli Google Cloud, klikając 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, wykonywania zapytań i analizowania logów. Domyślnie ten widok obejmuje logi wygenerowane ze wszystkich systemów dostępnych dla Twojego projektu, w tym z dzienników wygenerowanych poza Inteligentnym domem. Dlatego tak ważne jest używanie tych dzienników, filtrując je pod kątem zdarzeń, które chcesz debugować. Omówimy to dokładniej w sekcjach dotyczących debugowania.

3. Debugowanie problemów z przekazywaniem

Pierwszym rodzajem danych, które omówimy, są zdarzenia zlecania uruchomienia standardu Matter. Przekazywanie dostępu to zestaw czynności, które użytkownik musi wykonać, aby skonfigurować urządzenie Matter po raz pierwszy.

Podczas konfigurowania urządzenia zachodzi zestaw interakcji między urządzeniem Matter, aplikacją Google Home oraz tkaniną Matter. Ten obraz przedstawia niektóre z tych zdarzeń:

Więcej informacji o poszczególnych krokach znajdziesz na stronie uruchamiania w standardowej wersji Matter. W tej sekcji omówimy narzędzia i metody debugowania problemów z przekazywaniem zamówień.

Użyj Google Home Analytics.

Stworzyliśmy zestaw danych, które ułatwią Ci zbadanie problemów z przekazywaniem zamówień. Dzięki temu możesz śledzić zdarzenia i dowiedzieć się, na jakim etapie mogą wystąpić błędy. Znajdziesz je w panelu integracji Matter, jak omówiliśmy w poprzedniej sekcji.

Wykresy w tym panelu pokazują dane dotyczące uruchamiania urządzenia:

Wykres liczby urządzeń pokazuje liczbę prób uruchomienia aplikacji przez użytkowników w danym dniu. Wskaźnik sukcesu pokazuje postrzegany współczynnik sukcesu dla tych zdarzeń po stronie Google. Każda próba uruchomienia powoduje wygenerowanie zestawu zdarzeń z powiązanymi stanami. Jeśli w którymś z tych stanów wystąpi błąd, jest on też rejestrowany na wykresie z zestawieniem błędów.

Państwo, który wydał komisję:

• 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 prowizji, w polu zapytania możesz wyszukać hasło „clientUpdateLog” w połączeniu z ciągiem „severity>=ERROR”.

Dziennik błędów obsługi klienta 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, a także identyfikator produktu Matter, który pozwala zidentyfikować, które z Twoich produktów spowodowały błąd. Zestaw dzienników wygenerowanych w ramach tej samej próby uruchomienia korzysta z tego samego konta sessionId.

Korzystając z danych z Google Home Analytics, możesz zorientować się, na którym etapie może on się pojawić. Aby znaleźć główną przyczynę błędów w procesie uruchamiania urządzenia, czasem trzeba przeprowadzić dodatkowe debugowanie, korzystając z dzienników wygenerowanych przez urządzenie mobilne użyte w tym procesie. Potrzebujesz do tego narzędzia Android Debug Bridge.

Użycie Android Debug Bridge (ADB)

Innym sposobem rozwiązania problemów z przekazywaniem zamówień jest użycie narzędzia wiersza poleceń Android Debug Bridge (ADB). Uruchomienie odbywa się głównie między urządzeniem mobilnym a urządzeniem Matter, dlatego podczas uruchamiania można używać narzędzia ADB do uzyskiwania dostępu do dzienników wygenerowanych przez aplikację Google Home.

Zainstaluj narzędzia platformy

Narzędzie ADB wchodzi w skład narzędzi platformy Android SDK, które można zainstalować za pomocą Android Studio lub narzędzia wiersza poleceń sdkmanager.

Gdy zainstalujesz w systemie narzędzia platformy, zweryfikuj ADB, sprawdzając numer wersji w terminalu za pomocą tego polecenia:

$ adb -- version

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

Włącz debugowanie USB

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

Najpierw wykonaj te czynności, aby włączyć opcje programisty na swoim urządzeniu, a następnie włączyć debugowanie USB.

Dzięki temu ADB ma dostęp do logów wygenerowanych przez aplikacje aktualnie uruchomione na urządzeniu.

Pobierz identyfikator 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 to ostrzeżenie, kliknij Zezwól.
4. Wykonaj to polecenie z terminala, aby sprawdzić, czy komputer może uzyskać dostęp do telefonu przez ADB:

$ adb devices

Powinna to być 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> – będzie Ci potrzebna w kolejnych krokach.

Zbieranie informacji o systemie

W następnym kroku należy sprawdzić informacje o wersji systemu na urządzeniu i aplikacji.

• 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 i sprawą 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 zwrotów są obsługiwane przez nasz ekosystem. Zgłaszając się do zespołu pomocy w sprawie niepowodzenia podczas uruchamiania, zawsze podawaj w zgłoszeniach informacje o systemie.

Zbieranie logów błędów

Następnie rozpocznij proces zbierania dzienników, a potem wykonaj czynności związane z przeprowadzaniem zlecenia, aby wygenerować zdarzenia błędów, które chcesz debugować.

1. Uruchom poniższe polecenie, podając <phone-id>, a także <file-name>, gdzie logi będą zapisywane na komputerze (np. debug_file.txt).

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

Spowoduje to natychmiastowe uruchomienie procesu logowania. Jeśli plik nie istnieje, zostanie utworzony plik o podanej nazwie, a dzienniki z telefonu są dodawane do pliku po każdym zdarzeniu.

Kontynuuj konfigurowanie urządzenia Matter.

2. Po osiągnięciu błędu, który chcesz debugować, zatrzymaj rejestrowanie, naciskając Control+C w wyświetlonym oknie terminala.

Dzienniki powinny być teraz przechowywane w pliku logowania <file-name>. Ponieważ ten proces rejestruje logi z każdego uruchomionego procesu śledzonego na urządzeniu, będzie się w nim znajdowało wiele dzienników. Dlatego zawsze należy używać tych dzienników, przeszukując potrzebne wpisy.

Analiza logów błędów

Procesy uruchamiania są obsługiwane w podsystemie MatterCommissioner w GHA.

1. Kierując się główną strategią stosowaną przy analizowaniu błędów zlecania, wyszukaj błędy wygenerowane przez podsystem MatterCommissioner za pomocą tego polecenia:

$ grep "MatterCommissioner" <file-name>

Spowoduje to wygenerowanie danych wyjściowych zawierających zdarzenia z procesu składania zamówień.

2. Jeśli urządzenie Matter używa Thread, możesz też poszukać błędów wygenerowanych przez podsystem Thread, korzystając z tego polecenia:

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

Analizując plik dziennika wygenerowany przez proces debugowania ADB, staraj się także szukać określonych wzorców. Wiele błędów związanych z przekazywaniem zamówień zawiera ciąg „commissioning failure” w komunikatach o błędach.

3. Wyszukaj komunikat o niepowodzeniu uruchomienia za pomocą tego polecenia:

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

4. Debugowanie problemów z sterowaniem urządzeniem

Gdy użytkownicy skonfigurują urządzenia Matter i skonfigurują je w ekosystemie Google Home, będą mogli wydawać polecenia głosowo za pomocą Asystenta Google (np. „OK Google, włącz światło w salonie”) lub korzystając z interfejsu w aplikacji Google Home lub na ekranach Google Nest.

Specyfikacja sterowania między urządzeniami końcowymi a centrami Google odbywa się za pośrednictwem standardu Matter, więc po stronie sterowania urządzenia powinno występować mniej błędów. Niezależnie od tego udostępniamy dane i dzienniki, które służą do debugowania tego typu problemów.

Korzystanie z danych

W panelu integracji Matter zobaczysz kilka wskaźników dotyczących sterowania urządzeniami. Do oceny wydajności urządzeń dostępne są 3 wykresy w terenie:

W przypadku problemów z kontrolą często widzisz trendy spadków poziomu powodzenia i wzrosty na wykresie z podziałem błędów. Wykres z podziałem błędów pokazuje błędy przechwycone przez urządzenia Google Nest Hub i dotyczące przyczyny niepowodzenia próby sterowania urządzeniem.

Używanie dzienników

Każdy problem z kontrolą urządzenia Matter powoduje też wygenerowanie w systemie dziennika błędów. Te błędy można odfiltrować z eksploratora logów, wyszukując „executionLog”.

Logi błędów sterowania urządzeniami w standardzie 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 kontroli w elemencie statusType. Wiele błędów kontrolnych zawiera też externalDebugString – 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 urządzeń i ich kontrolą w standardzie Matter. Są też inne funkcje ekosystemu, dzięki którym możesz stosować zalecane przez nas metody, aby zapewnić wysoką jakość integracji.

Śledzenie aktualizacji OTA

Aby śledzić aktualizacje Bezprzewodowych urządzeń Matter (OTA) wydanych przez Google Home, udostępniamy zestaw danych pokazujących wersji sprzętu i oprogramowania urządzeń dostępnych w terenie.

Po opublikowaniu aktualizacji z poziomu konsoli obserwuj te dane:

W kolejnych dniach coraz więcej urządzeń w polu będzie otrzymuje nową wersję oprogramowania powiązaną z wersją OTA.

6. Poproś o pomoc

Google udostępnia narzędzia i dokumentację umożliwiającą debugowanie problemów ze standardem Matter, ale ponieważ ekosystem Matter jest nowy, pojawią się problemy, których nie ma w tych materiałach. W takich przypadkach możesz skontaktować się z nami lub społecznością, aby uzyskać pomoc.

Odwiedź kanały dla deweloperów

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

Choć każdy z tych kanałów jest okresowo monitorowany przez ten sam zespół, istnieją pewne kluczowe różnice w wyborze właściwego.

• Stack Overflow: jeśli masz pytania dotyczące implementacji lub potrzebujesz pomocy, skontaktuj się z nami oraz ze społecznością deweloperów inteligentnych domów. Najlepiej, gdy chcesz zapytać, jak rozwiązać problemy lub wdrożyć określoną funkcję.
• Śledzenie problemów: to oficjalny system śledzenia błędów prowadzony przez Google, za pomocą którego odbiorcy z zewnątrz mogą zgłaszać błędy w ekosystemie. Zapewnia on narzędzia internetowe, które umożliwiają załączanie plików i udostępnianie informacji poufnych. Narzędzie do śledzenia problemów najlepiej nadaje się do zgłaszania problemów z ekosystemem i udostępniania próśb o dodanie funkcji.
• Forum dla deweloperów: aby uzyskać wskazówki od oficjalnych ekspertów pomocy Google i ekspertów społeczności, możesz skontaktować się z nami na Forum dla deweloperów Nest. To forum jest najlepsze, jeśli chcesz uzyskać oficjalne wskazówki dotyczące programowania.

Zasubskrybuj newsletter dla deweloperów

Oprócz pytań na kanałach dla deweloperów publikujemy też kwartalny newsletter, w którym przedstawiamy nowe funkcje i aktualności na temat ekosystemu inteligentnego domu Google.

Aby otrzymywać newsletter dla deweloperów, możesz użyć formularza rejestracji.

7. Gratulacje

Gratulacje! Wiesz już, jak debugować integracje Matter przy użyciu zalecanych przez nas narzędzi i metod. Życzymy miłego korzystania z integracji Matter z Google Home.

Dalsze kroki

Wykonaj poniższe ćwiczenia i odkryj dodatkowe materiały:

• Poza korzystaniem z analityki do rozwiązywania problemów możesz też korzystać z pakietu Test Suite, aby przetestować integrację pod kątem potencjalnych problemów.
• Gdy Twoja integracja będzie gotowa do udostępnienia użytkownikom, następnym krokiem jest uzyskanie certyfikatu WWGH. W tym celu wykonaj czynności opisane na stronie Certyfikat.