Debugowanie integracji Matter

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

1. Zanim zaczniesz

Matter zapewnia użytkownikom płynne konfigurowanie urządzeń i sterowanie nimi na różnych platformach. 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ć często 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 monitorować trendy dotyczące problemów na urządzeniach w polu w sposób zbiorczy i rozwiązywać je za pomocą aktualizacji 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żna podłączyć do stacji roboczej (do celów logowania ADB);

Czego się nauczysz

• Jak używać narzędzi analitycznych do inteligentnego domu do monitorowania problemów z Matter na dużą skalę
• Jak posortować 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 danych projektu

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

Do Twojego projektu jest dostępnych kilka 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 Matter znajdziesz zestaw wykresów, które śledzą powodzenie wdrożenia oraz wdrażanie 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 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. W konsoli Google Cloud możesz go otworzyć, 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 zawiera logi generowane przez wszystkie systemy dostępne dla projektu, w tym logi generowane poza Smart Home. 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 na ten temat znajdziesz w sekcjach poświęconych debugowaniu.

3. Debugowanie problemów z uzyskiwaniem dostępu

Pierwszy typ danych, który omówimy, to zdarzenia zlecania Matter. Wdrożenie 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ń:

Aby dowiedzieć się więcej o każdym z tych kroków, zapoznaj się z stroną poświęconą uruchamianiu w podręczniku wprowadzającym do Matter. W tej sekcji omówimy narzędzia i techniki, które pomogą Ci rozwiązać problemy z uzyskiwaniem dostępu.

Korzystanie z Google Home Analytics

Utworzyliśmy zestaw danych, który pozwoli 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 z Matter, o którym była mowa w poprzedniej sekcji.

Wykresy w tym panelu zawierają dane o wprowadzaniu urządzenia do eksploatacji:

Wykres Liczba urządzeń pokazuje liczbę prób aktywacji przez użytkowników w określonym dniu. Wskaźnik sukcesu pokazuje szacowany wskaźnik sukcesu tych zdarzeń po stronie Google. Każda próba uruchomienia generuje zestaw zdarzeń z powiązanymi stanami. Gdy wystąpi błąd w dowolnym z tych stanów, zostanie on również uwzględniony 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 odfiltrować błędy inicjalizacji, w polu zapytania wyszukaj „clientUpdateLog” w połączeniu z „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 wdrożenia 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 na rozwiązanie problemów z uruchomieniem jest użycie narzędzia wiersza poleceń Android Debug Bridge (ADB). Ponieważ proces uruchamiania jest głównie obsługiwany przez urządzenie mobilne i urządzenie 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.

Pobieranie identyfikatora 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

Powinieneś otrzymać odpowiedź podobną 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 skontaktujesz się z zespołem pomocy w sprawie problemów z uruchomieniem, zawsze podaj w zgłoszeniu informacje o systemie.

Gromadzenie logów błędów

Następnie uruchom proces zbierania logów, a potem wykonaj kroki dotyczące uruchamiania, 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>

To powoduje 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 konfiguracyjne urządzenia obsługującego 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 zawsze należy korzystać z tych dzienników, wyszukując potrzebne wpisy.

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>

Podczas analizowania pliku dziennika wygenerowanego przez proces debugowania ADB poszukaj 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. Aby wyszukać komunikat o błędzie uruchamiania, użyj tego polecenia:

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

4. Debugowanie problemów z kontrolowaniem urządzeń

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 w aplikacji Home lub na ekranach Google Nest.

Specyfikacja sterowania między urządzeniami końcowymi a Google Hubs 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 z Matter znajdziesz kilka danych dotyczących sterowania urządzeniami. Do oceny skuteczności urządzeń w warunkach rzeczywistych służą 3 krokujące wykresy:

W przypadku problemów z kontrolą zwykle widać tendencję spadkową w przypadku odsetka powodzeń i wzrostową na wykresie zestawienia błędów. Wykres zestawienia błędów zawiera błędy zarejestrowane przez urządzenia Google Nest Hubs dotyczące przyczyny niepowodzenia próby sterowania urządzeniem.

Korzystanie z logó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”.

Dzienniki błędów sterowania urządzeniem 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 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

Do tej pory dowiedziałeś się, jak obsługiwać wdrożenie urządzeń i rozwiązywać problemy z kontrolą w przypadku Matter. W ekosystemie są też inne funkcje, których możesz używać, oraz zalecane techniki, które 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 wydaniu aktualizacji z poziomu konsoli obserwuj 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 z Matter, ale ponieważ ekosystem Matter jest nowy, mogą pojawić się problemy, których te zasoby nie obejmują. W takich przypadkach możesz skontaktować się z nami lub z społecznością, aby uzyskać pomoc.

Odwiedź 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 stosować dany kanał.

• Stack Overflow: możesz kontaktować się z nami i z społecznością deweloperów urządzeń inteligentnego domu, aby zadać pytania dotyczące implementacji lub uzyskać wskazówki. 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. Zawiera ona narzędzia internetowe do dołączania plików i udostępniania 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. To forum jest najlepszym miejscem do uzyskiwania oficjalnych wskazówek dotyczących programowania.

Zapisz się na 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 rejestracji.

7. Gratulacje

Gratulacje! Udało Ci się debugować integracje z Matter za pomocą zalecanych narzędzi i technik. Życzymy udanego tworzenia integracji Matter z Google Home.

Dalsze kroki

Wypróbuj te ćwiczenia i poznaj dodatkowe materiały:

• Oprócz korzystania z analizy do rozwiązywania problemów możesz też użyć Test Suite, aby przetestować integrację pod kątem potencjalnych 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.