Debugowanie integracji Matter

1. Zanim zaczniesz

Matter zapewnia użytkownikom płynne i łatwe konfigurowanie urządzeń na różnych platformach oraz kontrolowanie ich działania. Jest to możliwe głównie dzięki wielu komponentom ekosystemu, które współpracują ze sobą w tle. Rozwiązywanie problemów z takimi systemami może być trudne dla nowych deweloperów, dlatego opracowaliśmy serię narzędzi i technik, które ułatwią Ci pracę jako deweloperowi Matter w Google Home.

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

Jako deweloper musisz mieć możliwość rozwiązywania problemów, które występują w trakcie cyklu tworzenia 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 laboratorium programistycznym omawiamy techniki, których możesz używać do obu tych celów.

Wymagania wstępne

• Ukończ przewodnik Wprowadzenie do Matter, korzystając z działającego projektu Matter i z konfiguracji urządzenia.
• 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 diagnozować błędy, uzyskując dostęp do dzienników błędów i zbierając informacje.
• Jak uzyskać dostęp do dokumentacji i zasobów pomocy dotyczących Matter.

2. Wyświetlanie statystyk Google Home

Monitorowanie wydajności ma kluczowe znaczenie dla udanej integracji z ekosystemem Google Home. Udostępniamy zestaw narzędzi do monitorowania deweloperom inteligentnych urządzeń domowych w Google Cloud Platform. 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 konsoli Google Cloud i kliknij Operacje > Monitorowanie > Panele.

Do Twojego projektu jest dostępnych wiele paneli (w tym inne usługi GCP). Panele udostępniane na potrzeby inteligentnego domu mają prefiks Google Home Analytics.

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

Po otwarciu jednego z tych paneli zobaczysz serię wykresów, które wyglądają tak:

Panele informacyjne Google Home zawierają różne wykresy, które pokazują szczegóły zdarzeń powiązanych z Twoim projektem. W przypadku każdego panelu integracji zobaczysz wykres pokazujący łączną liczbę żądań obsługiwanych przez projekt, wykres pokazujący współczynnik sukcesu danego typu integracji oraz kilka wykresów przedstawiających zaangażowane 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 widok domyślny z wykresami, który widzisz w panelach Google Home Analytics, to tylko widok utworzony dla Twojego projektu na podstawie danych z 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.

Dzienniki błędów

Eksplorator logów to zbiór narzędzi do pracy z logami zdarzeń wygenerowanymi w projekcie. W konsoli Google Cloud możesz do niego dotrzeć, 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, przeszukiwania 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 używać tych dzienników, filtrując je pod kątem zdarzeń, które chcesz debugować. Więcej informacji znajdziesz w sekcji poświęconej debugowaniu.

3. Debugowanie problemów ze realizacją transakcji

Pierwszy typ danych, który omówimy, to zdarzenia zlecania Matter. Uruchomienie to zestaw czynności, które użytkownik musi wykonać, aby po raz pierwszy skonfigurować urządzenie Matter.

Podczas uruchamiania urządzenia dochodzi do interakcji między urządzeniem Matter, aplikacją Google Home i platformą Matter. Na poniższym obrazku pokazano 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, które pomogą Ci debugować problemy z uruchomieniem.

Korzystanie z Google Home Analytics

Utworzyliśmy zestaw danych, które pomogą Ci zbadać problemy z uruchomieniem, śledząc zdarzenia i określając, 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 o wprowadzaniu urządzenia do eksploatacji:

Wykres liczby urządzeń pokazuje liczbę prób uruchomienia przez użytkowników w danym dniu. Wskaźnik sukcesu pokazuje wskaźnik sukcesu tych zdarzeń z perspektywy Google. Każda próba uruchomienia powoduje wygenerowanie zestawu zdarzeń z powiązanymi stanami. Gdy wystąpi błąd w dowolnym z tych stanów, jest on również rejestrowany na wykresie zestawienia błędów.

Stany w przypadku konfiguracji:

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

Aby wyświetlić szczegółowe informacje o tych zdarzeniach, kliknij Operacje > Logowanie > Eksplorator logów. Aby filtrować błędy w komisynach, w polu zapytania możesz wyszukać ciąg „clientUpdateLog” połączony z ciągiem „severity>=ERROR”.

Dziennik błędów wdrożenia 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 wdrożenia i kodu stanu dziennik błędów zawiera sygnatury czasowe zarejestrowanego błędu oraz identyfikator produktu Matter, który pozwala określić, który z Twoich produktów spowodował błąd. Zestaw logów wygenerowanych podczas tej samej próby uruchomienia zawiera sessionId.

Korzystanie z danych z Google Home Analytics pozwala określić, na jakim etapie może wystąpić problem. Aby znaleźć przyczynę błędów podczas uruchamiania urządzenia, czasami trzeba przeprowadzić dodatkowe debugowanie, korzystając z dzienników wygenerowanych przez urządzenie mobilne używane w procesie uruchamiania. W tym celu potrzebujesz Android Debug Bridge.

Korzystanie z Android Debug Bridge (ADB)

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

Instalowanie narzędzi platformy

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

Po zainstalowaniu narzędzi platformy w systemie sprawdź 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łączanie debugowania USB

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

Najpierw wykonaj czynności, aby włączyć opcje dla programistów na urządzeniu, a następnie włącz debugowanie USB.

Umożliwia to ADB dostęp do dzienników generowanych przez aplikacje, które są obecnie 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 z uruchomionym serwerem ADB.

Na telefonie może pojawić się komunikat o ostrzeganiu dotyczący debugowania przez USB z zapytaniem, czy chcesz zezwolić komputerowi na dostęp do informacji z telefonu:

3. Jeśli pojawi się ten komunikat, kliknij Zezwalaj.
4. Aby sprawdzić, czy komputer może uzyskać dostęp do telefonu przez ADB, w terminalu uruchom polecenie list devices:

$ adb devices

Powinna to być odpowiedź podobna do tej:

List of devices attached
<phone-id>    device

Wartość <phone-id> to ciąg znaków alfanumerycznych, który jednoznacznie identyfikuje Twoje urządzenie.

5. Zapamiętaj wartość <phone-id>, aby użyć jej w kolejnych 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 za pomocą Usług 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 problemów z uruchomieniem, zawsze podawaj w zgłoszeniach informacje o systemie.

Gromadzenie logów błędów

Następnie uruchom proces zbierania logów, a potem wykonaj kroki dotyczące uruchomienia, aby wygenerować zdarzenia błędu, które chcesz debugować.

1. Uruchom to polecenie, podając <phone-id> oraz <file-name>, gdzie na komputerze mają być zapisywane dzienniki (np. debug_file.txt).

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

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

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

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

Logi powinny być teraz przechowywane w pliku logowania <file-name>. Ponieważ ten proces rejestruje logi z każdego uruchomionego procesu na urządzeniu, w pliku będzie dużo logów. Dlatego należy zawsze używać tych dzienników do przeszukiwania potrzebnych wpisów.

Analizowanie dzienników błędów

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

1. Zgodnie z główną strategią stosowaną podczas analizowania błędów w komercjalizacji poszukaj błędów generowanych przez podsystem MatterCommissioner za pomocą tego polecenia:

$ grep "MatterCommissioner" <file-name>

Generuje dane wyjściowe zawierające zdarzenia z procesu uruchamiania.

2. Jeśli urządzenie Matter korzysta z protokołu Thread, możesz też sprawdzić błędy generowane przez ten podsystem za pomocą tego polecenia:

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

Analizując plik dziennika wygenerowany przez proces debugowania ADB, zwracaj też uwagę na określone wzorce. Wiele błędów związanych z uruchomieniem zawiera w komunikacie o błędzie ciąg znaków „commissioning failure”.

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

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

4. Debugowanie problemów z kontrolowaniem urządzenia

Gdy użytkownicy skonfigurują i uruchomią urządzenia Matter w ekosystemie Google Home, będą mogli wydawać polecenia głosowe za pomocą Asystenta Google (np. „OK Google, włącz światła w moim salonie”) lub za pomocą interfejsu aplikacji Home lub ekranów Google Nest.

Specyfikacja sterowania między urządzeniami końcowymi a bramkami Google jest obsługiwana przez Matter, co powinno zmniejszyć liczbę błędów po stronie sterowania urządzeniem. Udostępniamy też dane i logo, 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 z kontrolą urządzenia Matter powoduje też wygenerowanie w systemie logu błędów. Te błędy można 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 prośbą o sterowanie w statusType. Wiele błędów kontroli zawiera też externalDebugString, czyli krótki komunikat o błędzie, który wyjaśnia, na czym on polega.

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, w przypadku których możesz korzystać z zalecanych przez nas technik, aby zapewnić wysoką jakość integracji.

Śledzenie aktualizacji OTA

Aby śledzić wersje aktualizacji OTA na urządzeniach Matter wydawane przez Google Home, udostępniamy zestaw danych, który pokazuje wersje sprzętu i oprogramowania urządzeń w użyciu.

Po wprowadzeniu aktualizacji na konsoli sprawdzaj te dane:

W dniach po wydaniu coraz więcej urządzeń w polu otrzyma nową wersję oprogramowania powiązaną z Twoim wydaniem OTA.

6. Uzyskiwanie 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 możesz skontaktować się z nami lub z społecznością, aby uzyskać pomoc.

Otwórz kanały dla deweloperów

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

Każdy z tych kanałów jest monitorowany okresowo przez ten sam zespół, ale istnieją pewne kluczowe różnice dotyczące tego, kiedy należy używać danego kanału.

• Stack Overflow: możesz skontaktować się z nami i społecznością deweloperów inteligentnych domów, aby zadać pytania dotyczące wdrożenia lub uzyskać pomoc. Ten kanał jest najlepszy do zadawania pytań o rozwiązywanie problemów lub wdrażanie określonych funkcji.
• System śledzenia problemów: to oficjalny system śledzenia problemów prowadzony przez Google, w którym zewnętrzni odbiorcy 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 do udostępniania próśb o dodanie funkcji.
• Forum programistów: aby uzyskać wskazówki od oficjalnego zespołu pomocy Google i ekspertów z społeczności, możesz skontaktować się z nimi na forum 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 których można zadawać pytania, co kwartał publikujemy newsletter, w którym informujemy o nowych funkcjach i aktualizacjach dotyczących ekosystemu Google Smart Home.

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:

• Oprócz korzystania z analizy do rozwiązywania problemów możesz też użyć Test Suite, aby sprawdzić, czy integracja nie powoduje żadnych problemów.
• Gdy integracja będzie gotowa do udostępnienia, możesz uzyskać certyfikat WWGH. Aby to zrobić, wykonaj czynności opisane na stronie Certyfikacja.