Debugowanie integracji spraw

1. Zanim zaczniesz

Matter zapewnia użytkownikom płynną konfigurację i kontrolę na wielu platformach. Jest to możliwe głównie dzięki temu, że wiele ekosystemowych komponentów współpracuje ze sobą w tle. Tego typu systemy mogą często zniechęcać nowych deweloperów, dlatego opracowaliśmy szereg narzędzi i technik, które ułatwiają życie Matterowi dzięki Google Home.

W tym ćwiczeniu z programowania omawiamy 3 główne składniki Matter. W przypadku każdego z tych systemów Google udostępnia zestaw narzędzi do rozwiązywania problemów dla deweloperów gromadzonych z telefonów i koncentratorów:

Deweloperzy muszą mieć możliwość eliminowania problemów, które pojawiają się podczas programowania urządzeń. Po uruchomieniu projektu musisz monitorować trendy dotyczące urządzeń w terenie i rozwiązać je za pomocą aktualizacji oprogramowania. Ćwiczenia z programowania obejmują techniki, które można wykorzystać do obu tych celów.

Wymagania wstępne

• Wykonaj czynności opisane w artykule Pierwsze kroki z Matter dotyczącym prawidłowego działania projektu i urządzenia.
• mieć telefon z Androidem, który można połączyć ze stacją roboczą (w celu logowania dzienników ADB).

Czego się nauczysz

• Jak korzystać z narzędzi analitycznych do inteligentnego domu, aby monitorować problemy typu Matter na dużą skalę.
• Dowiedz się, jak posortować błędy za pomocą logów błędów i gromadzenia informacji.
• Jak uzyskać dostęp do dokumentacji Matter i zasobów pomocy, aby uzyskać wsparcie

2. Wyświetl statystyki z Google Home

Monitorowanie wydajności ma kluczowe znaczenie dla powodzenia integracji z ekosystemem Google Home. Udostępniamy zestaw narzędzi do monitorowania inteligentnym domom w Google Cloud Platform. Za pomocą tych narzędzi możesz mierzyć wydajność swojego projektu.

Dostęp do wskaźników projektu

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

W Twoim projekcie jest kilka paneli (w tym innych usług GCP ). Panele dostarczane dla inteligentnego domu mają prefiks Google Analytics Analytics.

Obecnie mamy ogólny panel obejmujący cały projekt oraz panele dotyczące konkretnej integracji (chmury, lokalne, sprawy) lub urządzeń (kamery). Panele te zawierają dane tylko wtedy, gdy masz integrację odpowiedniego typu, a także działający projekt realizujący żądania.

Gdy otworzysz jeden z tych paneli, zobaczysz wykres, który wygląda tak:

Panele informacyjne w Google Home zawierają różne wykresy przedstawiające wydarzenia powiązane z Twoim projektem. Każdy panel integracji zawiera wykres przedstawiający łączną liczbę żądań obsługiwanych w projekcie, wykres przedstawiający odsetek sukcesów danego typu integracji oraz kilka wykresów przedstawiających typy urządzeń i cechy. Dodatkowo w standardzie Matter znajdziesz zestaw wykresów, które pozwolą Ci śledzić realizację zamówień oraz wdrażanie aktualizacji na urządzeniach.

Pamiętaj, że domyślny widok z wykresami widoczny w panelach informacyjnych w Google Home Analytics to tylko widok utworzony przez Ciebie dla Twojego projektu z wykorzystaniem danych inteligentnego domu. Za pomocą narzędzia Metrics Explorer możesz też tworzyć własne wykresy na podstawie tych samych danych podstawowych i zapisywać je w niestandardowych panelach.

Dzienniki błędów dostępu

Eksplorator logów to zbiór narzędzi do pracy z dziennikami zdarzeń wygenerowanymi w projekcie. Aby uzyskać do niego dostęp w Google Cloud Console, kliknij Operacje > Logowanie > Eksplorator logów.

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

Okno eksploratora zawiera różne narzędzia do wyświetlania, filtrowania, wyszukiwania i analizowania logów. Domyślnie wyświetlane są logi wygenerowane przez wszystkie systemy dostępne w projekcie, w tym logi wygenerowane poza inteligentnym domem. Dlatego tak ważne jest korzystanie z tych dzienników do filtrowania zdarzeń, które chcesz zdebugować. Omówimy to dokładniej w sekcji debugowania.

3. Debugowanie problemów ze strategią Prowizje

Pierwszym rodzajem danych, które przyjrzymy się zleceniu, jest zdarzenia prowizji w sprawie Matter. Prowizja odnosi się do zestawu czynności wymaganych przez użytkownika do skonfigurowania urządzenia Matter po raz pierwszy.

Podczas uruchamiania urządzenia między urządzeniami Matter, aplikacją Google Home i tkaniną Matter odbywa się zestaw interakcji. Grafika przedstawia niektóre z tych zdarzeń:

Więcej informacji na temat każdego z tych etapów znajdziesz na stronie prowizji w aplikacji Matter Primer. W tej sekcji omówimy narzędzia i techniki debugowania problemów ze strategią prowizji.

Używaj Google Home Analytics

Aby pomóc Ci w sprawdzeniu problemów z prowizjami, możesz śledzić zdarzenia oraz zrozumieć, na jakim etapie mogą występować błędy. Znajdziesz je w panelu integracji spraw, jak wspomnieliśmy w poprzedniej sekcji.

Wykresy w tym panelu zawierają dane na temat prowizje urządzenia:

Wykres liczby urządzeń pokazuje liczbę prób uruchomienia zamówienia przez użytkowników z danego dnia. Wskaźnik sukcesu postrzega postrzegany przez Google wskaźnik sukcesu tych zdarzeń. Każda próba prowizji generuje zbiór zdarzeń z powiązanymi stanami. Gdy w którymkolwiek z tych stanów wystąpi błąd, dane te są również zapisywane na wykresie zestawienia błędów.

Stany prowizyjne:

• ROZPOCZĘTE
• ONboardingING_PAYLOAD_GENERATED,
• LOKALNA_DOSTĘPNA_SKUTECZNOŚĆ
• POZYTYWNY POŁĄCZENIE
• BEZ ZAKUPÓW
• COMISSIONING_Ukończono

Aby wyświetlić szczegółową wersję tych zdarzeń, kliknij Operacje > Logowanie > Eksplorator logów. Aby filtrować błędy dotyczące prowizji, możesz wyszukać w polu zapytania „clientUpdateLog” i „severity>=ERROR”.

Dziennik błędów prowizji w sprawie 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"
}

Dziennik błędów zawiera oprócz stanu prowizji i kodu stanu sygnatury czasowe błędu, a także identyfikator produktu Matter, który pozwala zidentyfikować produkty, które spowodowały błąd. Zbiór logów wygenerowanych podczas tej samej próby zamówienia ze współdzieleniem korzysta z sessionId.

Dzięki danym z Google Home Analytics dowiesz się, na którym etapie może występować problem. Aby znaleźć główną przyczynę błędów zlecania urządzenia, czasem może być konieczne przeprowadzenie dodatkowego debugowania przy użyciu dzienników wygenerowanych na urządzeniu mobilnym. W tym celu potrzebujesz narzędzia Android Debug Bridge.

Używanie Android Debug Bridge (ADB)

Innym sposobem na rozwiązanie problemów z prowizjami jest użycie narzędzia wiersza poleceń Androida Debug Bridge (ADB). Prowizje są obsługiwane głównie między urządzeniem mobilnym a urządzeniem Matter, dlatego za pomocą narzędzia ADB można uzyskać dostęp do dzienników wygenerowanych przez aplikację Google Home w trakcie jego uruchamiania.

Instalowanie narzędzi platformy

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

Po 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.

Włącz debugowanie USB

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

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

Dzięki temu ADB ma dostęp do dziennikó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 z serwerem ADB.

Możesz zobaczyć na telefonie komunikat z ostrzeżeniem na temat debugowania USB, z pytaniem, czy chcesz zezwolić komputerowi na dostęp do informacji z telefonu:

3. Jeśli wyświetli się ten komunikat, kliknij Zezwól.
4. Uruchom w terminalu polecenie listy urządzeń, aby sprawdzić, czy komputer ma dostęp do telefonu przez ADB, używając tego polecenia:

$ adb devices

Otrzymasz odpowiedź podobną do tej:

List of devices attached
<phone-id>    device

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

5. Zapamiętaj wartość <phone-id> do użycia w kolejnych krokach.

Zbieranie informacji o systemie

Teraz sprawdź informacje o wersji aplikacji i systemu na urządzeniu.

• Aby sprawdzić wersję Androida:

$ 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 stroną główną 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 zwracane są obsługiwane przez nasz ekosystem. Kontaktując się z zespołem pomocy w przypadku awarii prowizji, zawsze podawaj w zgłoszeniach informacje systemowe.

Zbieranie logów błędów

Następnie rozpocznij proces gromadzenia logów, a następnie wykonaj czynności dotyczące prowizji, aby wygenerować zdarzenia błędu, które chcesz debugować.

1. Uruchom podane niżej polecenie, podając plik <phone-id> oraz <file-name>, w którym dzienniki będą zapisywane na komputerze (np. debug_file.txt).

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

Spowoduje to natychmiastowe rozpoczęcie procesu logowania. Zostanie utworzony plik o podanej nazwie, jeśli jeszcze nie istnieje. Dzienniki z telefonu są dodawane do pliku po każdym zdarzeniu.

Prowizje możesz przejść na urządzeniu Matter.

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

Logi powinny być teraz przechowywane w pliku dziennika <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 używaj tych wpisów do wyszukiwania wpisów.

Analizowanie logów błędów

Prowizje są obsługiwane w podsystemie o nazwie MatterCommissioner w GHA.

1. Korzystając z głównej strategii używanej do analizowania błędów prowizji, poszukaj błędów wygenerowanych przez podsystem MatterCommissioner za pomocą tego polecenia:

$ grep "MatterCommissioner" <file-name>

Spowoduje to wygenerowanie danych wyjściowych ze zdarzeń z prowizje.

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

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

Podczas analizowania pliku dziennika wygenerowanego w ramach procesu debugowania ADB poszukaj pewnych wzorców. Wiele błędów prowizji zawiera ciąg „commissioning failure” w komunikacie o błędzie.

3. Wyszukaj komunikat o błędzie dotyczący prowizji, używając tego polecenia:

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

4. Debugowanie problemów z urządzeniem

Po skonfigurowaniu i zleceniu urządzeń Matter w ekosystemie Google Home użytkownicy mogą wydawać polecenia 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 Centrum Google zapośredniczona jest przez Matter, dlatego po stronie sterowania urządzeniem prawdopodobnie powinno być mniej błędów. Niezależnie od tego udostępniamy też wskaźniki i dzienniki, które ułatwiają debugowanie takich problemów.

Używanie danych

W panelu integracji Matter znajdziesz kilka danych dotyczących kontroli urządzenia. Do oceny wydajności urządzeń w terenie służą 3 wykresy:

W przypadku problemów z kontrolą często występują tendencje spadkowe odsetka odsetka sukcesu i trendu na wykresie podziału błędów. Wykres z podziałem błędów przedstawia błędy zarejestrowane przez Google Nest Hub w przypadku nieudanej próby sterowania urządzeniem.

Używanie dzienników

Każdy problem z kontrolą urządzenia Matter generuje też w systemie dziennik błędów. Te błędy można odfiltrować z eksploratora logów przez wyszukanie „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 związany z żądaniem kontrolnym w statusType. Wiele błędów kontrolnych zawiera też externalDebugString – krótki komunikat o błędzie z opisem błędu.

5. Debugowanie innych funkcji

Do tej pory nauczyliśmy się obsługiwać zamówienia w ramach usługi Matter i sterować nimi. Istnieją też inne funkcje w ekosystemie, które możesz stosować w naszych zalecanych metodach, aby zapewnić wysoką jakość integracji.

Śledzenie aktualizacji OTA

Aby śledzić wydania aktualizacji bezprzewodowych urządzeń Matter publikowanych przez Google Home, udostępniamy zestaw danych pokazujących wersje sprzętu i oprogramowania urządzeń w terenie.

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

Zauważysz, że w ciągu dni od premiery na coraz większej liczbie urządzeń pojawi się nowa wersja oprogramowania powiązana z wersją OTA.

6. Pomoc dotycząca wyszukiwania

Google udostępnia narzędzia i dokumenty umożliwiające debugowanie problemów ze standardem Matter, ale ponieważ ekosystem Matter jest nowy, pojawią się kwestie, których nie będziemy omawiać. W takich przypadkach możesz skontaktować się z nami lub społecznością, aby uzyskać pomoc.

Odwiedź kanały dla deweloperów

Istnieją 3 kanały dewelopera aktywnie monitorowane w Google:

Chociaż każdy z tych kanałów jest monitorowany okresowo przez ten sam zespół, istnieją pewne istotne różnice w zakresie ich używania.

• Stack Overflow: możesz skontaktować się z nami i społecznością programistów korzystających z funkcji inteligentnego domu, jeśli masz pytania dotyczące implementacji lub potrzebujesz pomocy. Z tego kanału dowiesz się, jak rozwiązać problemy i zaimplementować określone funkcje.
• Issue Tracker: jest to oficjalny system śledzenia problemów opracowany przez Google, w ramach którego osoby z zewnątrz mogą zgłaszać błędy w ekosystemie. Udostępnia ona narzędzia internetowe do dołączania plików i udostępniania w razie potrzeby poufnych informacji. Korzystanie z narzędzia Issue Tracker najlepiej nadaje się do raportowania problemów z ekosystemem lub przesyłania próśb o dodanie funkcji.
• Forum dla programistów: aby uzyskać porady od oficjalnego zespołu pomocy Google i ekspertów ds. społeczności, możesz się z nim skontaktować na Forum dla deweloperów Nest. To forum jest najlepsze, aby \uzyskiwać oficjalne wskazówki dotyczące programowania.

Zasubskrybuj newsletter dla deweloperów

Poza odwiedzaniem kanałów dla deweloperów publikujemy też kwartalny newsletter zawierający informacje o nowych funkcjach i aktualności dotyczące ekosystemu Google Smart Home.

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

7. Gratulacje

Gratulacje! Udało Ci się nauczyć debugowania instancji Matter za pomocą polecanych przez nas narzędzi i technik. Życzymy miłego korzystania z integracji Matter z Google Home.

Dalsze kroki

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

• Oprócz rozwiązywania problemów za pomocą statystyk możesz też używać pakietu testowego do testowania integracji pod kątem potencjalnych problemów.
• Następnym krokiem po uzyskaniu integracji jest udostępnienie projektu WWGH. Aby to zrobić, wykonaj czynności opisane na stronie Certyfikacja.