Debugowanie integracji Matter

1. Zanim zaczniesz

Matter zapewnia użytkownikom płynną konfigurację i kontrolę na wielu platformach. Jest to możliwe głównie dzięki wielu komponentom ekosystemu, które współdziałają ze sobą za kulisami. Systemy rozwiązywania problemów, takie jak ten, mogą być zniechęcające dla nowych deweloperów, dlatego opracowaliśmy szereg narzędzi i technik, aby ułatwić Ci życie jako deweloperowi ze standardu Matter przy użyciu Google Home.

To ćwiczenie z programowania obejmuje 3 główne komponenty standardu Matter. W przypadku każdego z tych systemów Google udostępnia deweloperom zestaw statystyk rozwiązywania problemów z telefonami i centrami:

Jako deweloper musisz mieć możliwość eliminowania problemów, które pojawiają się w trakcie cyklu programowania urządzenia. Po uruchomieniu projektu musisz zbiorczo sprawdzać trendy dotyczące problemów z urządzeniami w terenie i naprawiać je przez aktualizacje oprogramowania. W tym ćwiczeniu z programowania omawiamy techniki, które można wykorzystać w obu tych celach.

Wymagania wstępne

• Wykonaj czynności opisane w przewodniku Pierwsze kroki ze standardem Matter, aby dowiedzieć się, jak skonfigurować działający projekt i urządzenie w ramach standardu 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 ze standardem Matter na dużą skalę.
• jak klasyfikować błędy przez dostęp do dzienników błędów i zbieranie informacji;
• Jak uzyskać dostęp do dokumentacji Matter i korzystać z zasobów pomocy w celu uzyskania pomocy

2. Wyświetl statystyki dotyczące Google Home

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

Dostęp do wskaźników projektu

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

W projekcie może być dostępnych wiele paneli (m.in. inne usługi GCP). Panele informacyjne dostępne w inteligentnym domu mają prefiks Google Home Analytics.

Obecnie mamy panel ogólny obejmujący cały projekt oraz panele do poszczególnych integracji (chmura, lokalna, Matter) lub typów urządzeń (Kamery). Te panele zawierają dane tylko wtedy, gdy masz integrację odpowiedniego typu oraz działający projekt realizujący żądania.

Po otwarciu panelu 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 znajduje się wykres, który pokazuje łączną liczbę żądań obsługiwanych przez Twój projekt, wykres wskaźnika sukcesu dla danego typu integracji oraz kilka wykresów obrazujących powiązane z nim typy i cechy urządzeń. Dodatkowo w standardzie Matter dostępny jest zestaw wykresów, które pozwalają śledzić realizację uruchomienia oraz wdrożenia aktualizacji na urządzeniach.

Pamiętaj, że domyślny widok z wykresami, które widzisz w panelach informacyjnych w Google Home Analytics, to tylko widok, który utworzyliśmy dla Twojego projektu na podstawie danych dotyczących inteligentnego domu. Za pomocą narzędzia Metrics Explorer możesz też tworzyć własne wykresy na podstawie tych samych bazowych 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ń wygenerowanymi w projekcie. Aby uzyskać do niego dostęp w konsoli Google Cloud, otwórz 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 przedstawia logi wygenerowane ze wszystkich systemów dostępnych dla Twojego projektu, w tym logi generowane poza inteligentnym domem. Dlatego tak ważne jest, aby z nich korzystać, filtrując zdarzenia, które chcesz debugować. Omówimy to dokładniej w sekcjach dotyczących debugowania.

3. Debugowanie problemów ze realizacją transakcji

Pierwszym rodzajem danych, które się przyjrzymy, są zdarzenia uruchamiania standardu Matter. Przekazywanie oznacza zestaw czynności, które użytkownik musi wykonać, aby po raz pierwszy skonfigurować urządzenie Matter.

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

Więcej informacji o każdym z tych kroków znajdziesz na stronie rozpoczęcia procesu w narzędziu Matter Primer. W tej sekcji omówimy narzędzia i techniki umożliwiające debugowanie problemów z uruchamianiem.

Korzystaj z Statystyk Google Home

Przygotowaliśmy zestaw danych, dzięki którym możesz zbadać problemy z realizacją zadań przez śledzenie zdarzeń i ustalenie, na którym etapie mogą wystąpić błędy. Znajdziesz je w panelu integracji spraw, jak opisaliśmy to w poprzedniej sekcji.

Wykresy w tym panelu zawierają dane dotyczące uruchomienia urządzenia:

Wykres liczby urządzeń pokazuje liczbę prób uruchomienia przez użytkowników w danym dniu. Wskaźnik sukcesu pokazuje postrzeganą skuteczność tych zdarzeń po stronie Google. Każda próba zlecenia uruchomienia generuje zbiór zdarzeń z powiązanymi stanami. Gdy wystąpi błąd w dowolnym z tych stanów, zostanie on również odnotowany na wykresie zestawienia błędów.

Stany realizacji:

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

Aby wyświetlić szczegółową wersję tych zdarzeń, przejdź do sekcji Operacje > Logowanie > Eksplorator logów. Aby przefiltrować błędy prowizji, możesz wyszukać „clientUpdateLog” połączono z „severity>=ERROR” w polu zapytania.

Dziennik błędów uruchamiania dla 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 uruchamiania i kodu stanu dziennik błędów zawiera sygnatury czasowe zarejestrowanego błędu oraz identyfikator produktu Matter, który pozwala zidentyfikować produkty, które spowodowały błąd. Zbiór logów wygenerowanych podczas tej samej próby uruchomienia korzysta z tego samego pola sessionId.

Dzięki danym z Google Home Analytics dowiesz się, na jakim etapie może wystąpić problem. Aby znaleźć główną przyczynę błędów uruchamiania urządzenia, może być konieczne przeprowadzenie dodatkowego debugowania przy użyciu dzienników wygenerowanych przez urządzenie mobilne używanego w tym procesie. Potrzebujesz do tego narzędzia Android Debug Bridge.

Używanie narzędzia Android Debug Bridge (ADB)

Innym sposobem rozwiązywania problemów z uruchamianiem jest użycie narzędzia wiersza poleceń Android Debug Bridge (ADB). Ponieważ uruchomienie odbywa się głównie między urządzeniem mobilnym a urządzeniem Matter, podczas uruchamiania można korzystać z narzędzia ADB, aby uzyskiwać dostęp do dzienników wygenerowanych przez aplikację Google Home.

Zainstaluj narzędzia platformy

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

Po pomyślnym zainstalowaniu narzędzi platformy w systemie 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 żadnych 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 urządzeniu, a potem włączyć debugowanie USB.

Dzięki temu ADB będzie mieć dostęp do logów generowanych przez aplikacje uruchomione obecnie 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.

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

3. Jeśli pojawi się to ostrzeżenie, kliknij Zezwól.
4. Wyślij z terminala polecenie listy urządzeń, by 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

Twój <phone-id> jest ciągiem alfanumerycznym, który jednoznacznie identyfikuje urządzenie.

5. Zapamiętaj wartość <phone-id> – użyj 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 Home / 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. Kontaktując się z zespołem pomocy w sprawie niepowodzenia uruchomienia, zawsze podawaj w zgłoszeniach informacje o systemie.

Pobieranie logów błędów

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

1. Uruchom poniższe polecenie, podając identyfikator <phone-id> oraz <file-name>, w którym logi zostaną zapisane na komputerze (np. debug_file.txt).

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

Spowoduje to natychmiastowe rozpoczęcie procesu logowania. Plik o podanej nazwie jest tworzony, jeśli jeszcze nie istnieje, a dzienniki z telefonu są do niego dodawane po każdym zdarzeniu.

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

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

Dzienniki powinny być teraz przechowywane w pliku logowania <file-name>. Ten proces rejestruje dzienniki każdego uruchomionego procesu śledzonego na urządzeniu, więc w tym pliku może być wiele dzienników. Dlatego należy zawsze używać tych dzienników do przeszukiwania potrzebnych wpisów.

Analizowanie logów błędów

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

1. Korzystając z głównej strategii wykorzystywanej podczas analizy błędów uruchamiania, 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 Twoje urządzenie Matter korzysta z usługi Thread, możesz też poszukać błędów wygenerowanych przez podsystem Thread za pomocą tego polecenia:

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

Analizując plik dziennika wygenerowany przez proces debugowania ADB, zwracaj też uwagę na niektóre wzorce. Wiele błędów uruchamiania obejmuje: „commissioning failure” w komunikacie o błędzie.

3. Wyszukaj komunikat o błędzie uruchomienia za pomocą tego polecenia:

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

4. Debugowanie problemów ze sterowaniem urządzeniem

Gdy użytkownicy skonfigurują i zlecą korzystanie z urządzeń Matter 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 za pomocą interfejsu w aplikacji Google Home lub na ekranach Google Nest.

Ze względu na to, że specyfikacja dotycząca sterowania między urządzeniami końcowymi a urządzeniami Google Hub jest zapośredniczona przez standard Matter, powinno być mniej błędów po stronie sterowania urządzeniem. Niezależnie od tego zapewniamy wskaźniki i logi, które ułatwiają debugowanie tego typu problemów.

Korzystanie z danych

W panelu integracji Matter zobaczysz kilka danych dotyczących sterowania urządzeniami. Są 3 wykresy, które są niezbędne do oceny wydajności urządzeń w terenie:

W przypadku problemów z kontrolą możesz zaobserwować spadek w odsetku powodzenia oraz trend wzrostowy na wykresie z podziałem błędów. Wykres z zestawieniem błędów pokazuje błędy zarejestrowane przez Google Nest Hub i informujące, dlaczego nie udało się przeprowadzić kontroli urządzenia.

Korzystanie z dzienników

Każdy problem ze sterowaniem urządzeniem Matter generuje też dziennik błędów w systemie. Te błędy możesz odfiltrować w eksploratorze logów, wyszukując „executionLog”.

Logi błędów kontroli urządzenia 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 kontrolnym w statusType. Wiele błędów kontrolnych zawiera też krótki komunikat o błędzie externalDebugString, który wyjaśnia, czego dotyczy błąd.

5. Debugowanie innych funkcji

Wiesz już, jak rozwiązywać problemy z uruchamianiem urządzenia i sterowaniem w przypadku standardu Matter. W ekosystemie są też inne funkcje, które możesz wykorzystać przy użyciu zalecanych przez nas technik, aby zapewnić integrację wysokiej jakości.

Śledzenie aktualizacji OTA

Aby śledzić wersje bezprzewodowych aktualizacji urządzeń Matter wydanych przez Google Home, udostępniamy zestaw danych, które pokazują wersje sprzętowe i oprogramowania urządzeń dostępnych w terenie.

Po przeprowadzeniu aktualizacji w konsoli zwróć uwagę na te dane:

Zauważysz, że w ciągu kilku dni po wydaniu nowej wersji coraz więcej urządzeń pobiera nową wersję oprogramowania z Twoją wersją OTA.

6. Szukaj pomocy

Google udostępnia narzędzia i dokumentację, które ułatwiają debugowanie problemów ze standardem Matter, ale ponieważ ekosystem Matter jest nowy, pojawią się problemy, których nie omówiono w tych materiałach. W takich przypadkach zawsze możesz skontaktować się z nami lub ze społecznością.

Odwiedź kanały dla deweloperów

W Google aktywnie monitorujemy 3 kanały deweloperów:

Chociaż każdy z tych kanałów jest co jakiś czas monitorowany przez ten sam zespół, istnieją pewne istotne różnice w zakresie tego, kiedy go używać.

• Stack Overflow: możesz skontaktować się z nami i społecznością deweloperów inteligentnego domu, jeśli masz pytania dotyczące implementacji lub potrzebujesz pomocy. Ten kanał jest najlepszy do rozwiązywania problemów lub wdrożenia określonej funkcji.
• Narzędzie do śledzenia problemów: to oficjalny prowadzony przez Google system do zgłaszania błędów, za pomocą których użytkownicy zewnętrzni mogą zgłaszać błędy w ekosystemie. Zapewnia narzędzia internetowe umożliwiające załączanie plików i udostępnianie informacji poufnych w razie potrzeby. Narzędzie Issue Tracker najlepiej nadaje się do zgłaszania problemów z ekosystemem lub przesyłania próśb o dodanie funkcji.
• Forum dla deweloperów: możesz uzyskać wskazówki od oficjalnej pomocy Google i ekspertów społeczności na Forum dla programistów Nest. Na tym forum możesz uzyskać oficjalne wskazówki dotyczące programowania.

Zasubskrybuj newsletter dla deweloperów

Oprócz odwiedzania kanałów dla deweloperów w razie pytań publikujemy też kwartalny newsletter, w którym przedstawiamy nowe funkcje i informujemy o stanie ekosystemu inteligentnego domu Google.

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

7. Gratulacje

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

Dalsze kroki

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

• Poza rozwiązywaniem problemów za pomocą narzędzi analitycznych możesz też za pomocą pakietu Test Suite przetestować integrację pod kątem potencjalnych problemów.
• Gdy integracja będzie gotowa do udostępnienia użytkownikom z całego świata, następnym krokiem będzie uzyskanie certyfikatu WWGH. Aby to zrobić, wykonaj czynności opisane na stronie Certyfikacja.