Migracja do Centrum deweloperów Google Home została zakończona.

Debugowanie lokalnego domu

1. Zanim zaczniesz

Integracje z inteligentnym domem umożliwiają Asystentowi Google sterowanie połączonymi urządzeniami w domach użytkowników. Aby utworzyć integrację typu chmura-chmura, musisz podać punkt końcowy webhooka w chmurze, który obsługuje intencje związane z inteligentnym domem. Na przykład gdy użytkownik powie „OK Google, włącz światła”, Asystent wyśle polecenie do usługi realizacji w chmurze, aby zaktualizować stan urządzenia.

Pakiet Local Home SDK ulepsza integrację inteligentnego domu, dodając lokalną ścieżkę, do której będą kierowane intencje inteligentnego domu bezpośrednio do urządzenia Google Home. Zwiększa to niezawodność i skraca czas oczekiwania na przetworzenie poleceń użytkowników. Umożliwia pisanie i wdrażanie aplikacji do realizacji lokalnej w języku TypeScript lub JavaScript, która identyfikuje urządzenia i wykonuje polecenia na dowolnym głośniku inteligentnym Google Home lub inteligentnym wyświetlaczu Google Nest. Aplikacja komunikuje się bezpośrednio z istniejącymi urządzeniami inteligentnymi użytkowników w lokalnej sieci komputerowej, używając standardowych protokołów do wykonywania poleceń.

Debugowanie integracji typu cloud-to-cloud jest kluczowym krokiem w tworzeniu integracji o jakości produkcyjnej, ale bez przydatnych i łatwych w użyciu narzędzi do rozwiązywania problemów i testowania jest to trudne i czasochłonne. Aby ułatwić debugowanie integracji typu cloud-to-cloud, dostępne są statystyki i logowanie Google Cloud Platform (GCP) oraz pakiet testów dla inteligentnego domu, które pomogą Ci identyfikować i rozwiązywać problemy z integracjami.

Wymagania wstępne

Przewodnik dla deweloperów tworzenia integracji typu chmura-chmura
Wykonaj ćwiczenia z programowania Włączanie lokalnej realizacji zamówień w przypadku integracji typu chmura-chmura

Co utworzysz

W tym module utworzysz lokalną realizację w przypadku integracji typu cloud-to-cloud i połączysz ją z Asystentem. Następnie debuguj aplikację Local Home za pomocą zestawu testów dla inteligentnego domu oraz pomiarów i logowania Google Cloud Platform (GCP).

Czego się nauczysz

Jak używać danych i logów GCP do identyfikowania i rozwiązywania problemów produkcyjnych.
Jak używać pakietu testów do identyfikowania problemów z funkcjonalnością i interfejsem API.
Jak korzystać z Narzędzi deweloperskich w Chrome podczas tworzenia aplikacji Local Home.

Czego potrzebujesz

Najnowsza wersja Google Chrome
Urządzenie z iOS lub Androidem z aplikacją Google Home
głośnik inteligentny Google Home lub wyświetlacz inteligentny Google Nest;
Node.js w wersji 10.16 lub nowszej
konto Google,
konto rozliczeniowe Google Cloud;

2. Uruchamianie aplikacji pralki

Pobieranie kodu źródłowego

Kliknij ten link, aby pobrać na komputer używany do programowania przykładowy kod do tego laboratorium.

…lub możesz sklonować repozytorium GitHub z wiersza poleceń:

$ git clone https://github.com/google-home/smarthome-debug-local.git

Informacje o projekcie

Aplikacja startowa zawiera podobne podkatalogi i funkcje w chmurze jak w przypadku samouczka dotyczącego włączania lokalnej realizacji w integracjach typu chmura-chmura. Zamiast app-start mamy tu jednak app-faulty. Zaczniemy od lokalnej aplikacji domowej, która działa, ale nie najlepiej.

Łączenie Analytics z Firebase

Użyjemy tego samego projektu, który został utworzony w ramach ćwiczenia Włączanie lokalnej realizacji w przypadku integracji typu cloud-to-cloud, ale wdrożymy pliki pobrane w ramach tego ćwiczenia.

Otwórz katalog app-faulty, a potem skonfiguruj interfejs wiersza poleceń Firebase za pomocą projektu integracji utworzonego w ramach ćwiczenia Włączanie lokalnej realizacji w przypadku integracji typu cloud-to-cloud:

$ cd app-faulty
$ firebase use <project-id>

Wdrażanie w Firebase

Przejdź do folderu app-faulty/functions i zainstaluj wszystkie niezbędne zależności za pomocą polecenia npm:

$ cd functions
$ npm install

Uwaga: jeśli zobaczysz poniższy komunikat, możesz go zignorować i kontynuować. Ostrzeżenie jest spowodowane starszymi zależnościami. Więcej informacji znajdziesz tutaj.

found 5 high severity vulnerabilities
  run `npm audit fix` to fix them, or `npm audit` for details

Otwórz katalog app-faulty/local/ i uruchom te polecenia, aby pobrać kompilator TypeScript i skompilować aplikację:

$ cd ../local
$ npm install
$ npm run build

Spowoduje to skompilowanie źródła index.ts (TypeScript) i umieszczenie w katalogu app-faulty/public/local-home/ tych treści:

bundle.js – skompilowane dane wyjściowe JavaScript zawierające aplikację lokalną i zależności.
index.html– strona hostingu lokalnego używana do wyświetlania aplikacji na potrzeby testowania na urządzeniu.

Po zainstalowaniu zależności i skonfigurowaniu projektu możesz po raz pierwszy uruchomić aplikację.

$ firebase deploy

Oto dane wyjściowe, które powinny się wyświetlić w konsoli:

...

✔ Deploy complete!

Project Console: https://console.firebase.google.com/project/<project-id>/overview
Hosting URL: https://<projectcd -id>.web.app

To polecenie wdraża aplikację internetową wraz z kilkoma Cloud Functions dla Firebase.

Aktualizowanie HomeGraph

Otwórz adres URL hostingu w przeglądarce (https://<project-id>.web.app), aby wyświetlić aplikację internetową. W interfejsie internetowym kliknij przycisk Odśwież, aby zaktualizować HomeGraph o najnowsze metadane urządzenia z aplikacji wadliwej pralki za pomocą Request Sync.

Otwórz aplikację Google Home i sprawdź, czy widzisz pralkę z nową nazwą „Uszkodzona pralka”. Pamiętaj, aby przypisać urządzenie do pomieszczenia, w którym znajduje się urządzenie Nest.

3. Uruchom inteligentną pralkę

Jeśli masz już za sobą ćwiczenia z programowania Włączanie realizacji lokalnej w przypadku integracji typu cloud-to-cloud, wirtualna inteligentna pralka powinna być już uruchomiona. Jeśli jest zatrzymane, pamiętaj, aby ponownie uruchomić urządzenie wirtualne.

Uruchom urządzenie

Przejdź do katalogu virtual-device/ i uruchom skrypt urządzenia, przekazując parametry konfiguracji jako argumenty:

$ cd ../../virtual-device
$ npm install
$ npm start -- \
  --deviceId=deviceid123 --projectId=<project-id> \
  --discoveryPortOut=3311 --discoveryPacket=HelloLocalHomeSDK

Sprawdź, czy skrypt urządzenia jest uruchamiany z oczekiwanymi parametrami:

(...): UDP Server listening on 3311
(...): Device listening on port 3388
(...): Report State successful

4. Testowanie aplikacji Local Home

Wysyłaj polecenia do urządzenia za pomocą poleceń głosowych wydawanych na urządzeniu Google Home, np.:

„OK Google, włącz pralkę”.

„OK Google, wymuś lokalne”.

„OK Google, zatrzymaj pralkę”.

Gdy po użyciu polecenia „force local” spróbujesz sterować pralką, Asystent Google odpowie: „Wygląda na to, że pralka jest obecnie niedostępna”.

Oznacza to, że urządzenie jest niedostępne przez ścieżkę lokalną. Działało to przed wydaniem polecenia „OK Google, wymuś lokalne”, ponieważ w przypadku niedostępności urządzenia przez ścieżkę lokalną wracamy do ścieżki w chmurze. Jednak po wymuszeniu lokalnego przetwarzania opcja powrotu do ścieżki w chmurze jest wyłączona.

Aby dowiedzieć się, na czym polega problem, skorzystajmy z dostępnych narzędzi: danych i logów Google Cloud Platform (GCP) oraz Narzędzi deweloperskich w Chrome.

5. Debugowanie aplikacji Local Home

W następnej sekcji użyjesz narzędzi udostępnionych przez Google, aby dowiedzieć się, dlaczego urządzenie jest niedostępne w sieci lokalnej. Możesz użyć Narzędzi deweloperskich w Chrome, aby połączyć się z urządzeniem Google Home, wyświetlić dzienniki konsoli i debugować aplikację Local Home. Możesz też wysyłać niestandardowe dzienniki do Cloud Logging, aby wiedzieć, jakie błędy najczęściej występują w aplikacji Local Home.

Łączenie Narzędzi deweloperskich w Chrome

Aby połączyć debuger z lokalną aplikacją do realizacji:

Sprawdź, czy urządzenie Google Home jest połączone z użytkownikiem, który ma uprawnienia dostępu do projektu w Konsoli Play.
Zrestartuj urządzenie Google Home, aby pobrało adres URL pliku HTML oraz konfigurację skanowania, którą umieścisz w konsoli programisty.
Uruchom Chrome na komputerze używanym do programowania.
Otwórz nową kartę Chrome i w polu adresu wpisz chrome://inspect, aby uruchomić inspektora.

Na stronie powinna pojawić się lista urządzeń, a adres URL aplikacji powinien być widoczny pod nazwą urządzenia Google Home.

Uruchamianie inspektora

Kliknij Sprawdź pod adresem URL aplikacji, aby otworzyć Narzędzia deweloperskie w Chrome. Kliknij kartę Konsola i sprawdź, czy widzisz treść intencji IDENTIFY wydrukowaną przez aplikację TypeScript.

Ten wynik oznacza, że moduł obsługi IDENTIFY został wywołany, ale wartość verificationId zwrócona w IdentifyResponse nie pasuje do żadnego z urządzeń w HomeGraph. Dodajmy kilka niestandardowych logów, aby dowiedzieć się, dlaczego tak się dzieje.

Dodawanie niestandardowych logów

Chociaż pakiet Local Home SDK wyświetla DEVICE_VERIFICATION_FAILED błąd, nie pomaga on w znalezieniu głównej przyczyny problemu. Dodajmy kilka niestandardowych logów, aby upewnić się, że prawidłowo odczytujemy i przetwarzamy dane skanowania. Pamiętaj, że jeśli odrzucimy obietnicę z błędem, komunikat o błędzie zostanie również wysłany do Cloud Logging.

local/index.ts

identifyHandler(request: IntentFlow.IdentifyRequest):
    Promise<IntentFlow.IdentifyResponse> {
  console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));

  const scanData = request.inputs[0].payload.device.udpScanData;
  if (!scanData) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_request', 'Invalid scan data');
    return Promise.reject(err);
  }

  // In this codelab, the scan data contains only local device id.
  // Is there something wrong here?
  const localDeviceId = Buffer.from(scanData.data);
  console.log(`IDENTIFY handler: received local device id
      ${localDeviceId}`);

  // Add custom logs
  if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_device', 'Invalid device id from scan data ' +
        localDeviceId);
    return Promise.reject(err);
  }

  const response: IntentFlow.IdentifyResponse = {
    intent: Intents.IDENTIFY,
    requestId: request.requestId,
    payload: {
      device: {
        id: 'washer',
        verificationId: localDeviceId.toString(),
      }
    }
  };
  console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));

  return Promise.resolve(response);
}

Zmień też wersję aplikacji lokalnego domu, abyśmy mogli sprawdzić, czy używamy prawidłowej wersji.

local/index.ts

const localHomeSdk = new App('1.0.1');

Po dodaniu niestandardowych logów musisz ponownie skompilować aplikację i wdrożyć ją w Firebase.

$ cd ../app-faulty/local
$ npm run build
$ firebase deploy --only hosting

Teraz ponownie uruchom urządzenie Google Home, aby mogło załadować zaktualizowaną aplikację lokalnego domu. Możesz sprawdzić, czy urządzenie Google Home korzysta z oczekiwanej wersji, przeglądając dzienniki konsoli w Narzędziach deweloperskich w Chrome.

Otwieranie Cloud Logging

Zobaczmy, jak używać Cloud Logging do znajdowania błędów. Aby uzyskać dostęp do Cloud Logging w projekcie:

W konsoli Cloud Platform otwórz stronę Projekty.
Wybierz projekt inteligentnego domu.
W sekcji Operacje wybierz Logowanie > Eksplorator logów.

Dostęp do danych logowania jest zarządzany za pomocą usługi Identity and Access Management (IAM) w przypadku użytkowników projektu integracji. Więcej informacji o rolach i uprawnieniach dotyczących logowania danych znajdziesz w artykule Kontrola dostępu w Cloud Logging.

Korzystanie z filtrów zaawansowanych

Wiemy, że w przypadku intencji IDENTIFY występują błędy, ponieważ ścieżka lokalna nie działa, gdyż nie można zidentyfikować urządzenia lokalnego. Chcemy jednak dokładnie wiedzieć, na czym polega problem, więc najpierw odfiltrujmy błędy występujące w funkcji obsługi IDENTIFY.

Kliknij przełącznik Pokaż zapytanie. Powinien on zmienić się w pole Konstruktor zapytań. W polu Konstruktor zapytań wpisz jsonPayload.intent="IDENTIFY" i kliknij przycisk Uruchom zapytanie.

W rezultacie otrzymasz wszystkie dzienniki błędów, które są zgłaszane w procedurze obsługi IDENTIFY. Następnie rozwiń ostatni błąd. W funkcji obsługi IDENTIFY znajdziesz wartości errorCode i debugString, które zostały ustawione podczas odrzucania obietnicy.

Z informacji debugString wynika, że lokalny identyfikator urządzenia nie ma oczekiwanego formatu. Aplikacja Local Home oczekuje, że lokalny identyfikator urządzenia będzie ciągiem znaków zaczynającym się od deviceid, po którym następują 3 cyfry, ale lokalny identyfikator urządzenia jest tutaj ciągiem szesnastkowym.

Naprawianie błędu

Wracając do kodu źródłowego, w którym analizujemy lokalny identyfikator urządzenia z danych skanowania, zauważamy, że podczas konwertowania ciągu znaków na bajty nie podaliśmy kodowania. Dane skanowania są odbierane jako ciąg szesnastkowy, więc podczas wywoływania funkcji Buffer.from() przekaż hex jako kodowanie znaków.

local/index.ts

identifyHandler(request: IntentFlow.IdentifyRequest):
    Promise<IntentFlow.IdentifyResponse> {
  console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));

  const scanData = request.inputs[0].payload.device.udpScanData;
  if (!scanData) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_request', 'Invalid scan data');
    return Promise.reject(err);
  }

  // In this codelab, the scan data contains only local device id.
  const localDeviceId = Buffer.from(scanData.data, 'hex');
  console.log(`IDENTIFY handler: received local device id
      ${localDeviceId}`);

  if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
    const err = new IntentFlow.HandlerError(request.requestId,
      'invalid_device', 'Invalid device id from scan data ' +
      localDeviceId);
    return Promise.reject(err);
  }

  const response: IntentFlow.IdentifyResponse = {
    intent: Intents.IDENTIFY,
    requestId: request.requestId,
    payload: {
      device: {
        id: 'washer',
        verificationId: localDeviceId.toString(),
      }
    }
  };
  console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));

  return Promise.resolve(response);
}

Zmień też wersję aplikacji lokalnego domu, abyśmy mogli sprawdzić, czy używamy prawidłowej wersji.

local/index.ts

const localHomeSdk = new App('1.0.2');

Po naprawieniu błędu skompiluj aplikację i wdroż ją ponownie w Firebase. W app-faulty/local uruchom:

$ npm run build
$ firebase deploy --only hosting

Testowanie poprawki

Po wdrożeniu ponownie uruchom urządzenie Google Home, aby mogło załadować zaktualizowaną aplikację lokalną. Sprawdź, czy wersja aplikacji lokalnej to 1.0.2. Tym razem w konsoli Narzędzi deweloperskich w Chrome nie powinny pojawić się żadne błędy.

Teraz możesz ponownie spróbować wysłać polecenia do urządzenia.

„OK Google, wymuś lokalne”.

„OK Google, zatrzymaj pralkę”.

„OK Google, włącz pralkę”.

…

„OK Google, wymuś domyślne”.

6. Uruchamianie pakietu testów dla inteligentnego domu

Po zweryfikowaniu urządzenia za pomocą sterowania dotykowego w aplikacji Google Home lub poleceń głosowych możesz użyć automatycznego pakietu testów dla inteligentnego domu, aby sprawdzić przypadki użycia na podstawie typów urządzeń i cech powiązanych z integracją. Pakiet testów przeprowadza serię testów, aby wykryć problemy z integracją, i wyświetla informacyjne komunikaty o nieudanych przypadkach testowych, aby przyspieszyć debugowanie przed przejrzeniem dzienników zdarzeń.

Uruchamianie zestawu testów dla inteligentnego domu

Aby przetestować integrację typu „chmura do chmury” za pomocą pakietu testowego, wykonaj te czynności:

W przeglądarce otwórz pakiet testów dla inteligentnego domu.
Zaloguj się w Google, klikając przycisk w prawym górnym rogu. Dzięki temu pakiet testowy może wysyłać polecenia bezpośrednio do Asystenta Google.
W polu Project ID (Identyfikator projektu) wpisz identyfikator projektu integracji typu Cloud-to-Cloud. Następnie kliknij DALEJ, aby kontynuować.
W kroku Ustawienia testu w sekcji Urządzenia i cechy powinna być widoczna wadliwa pralka.
Wyłącz opcję Test Request Sync (Testuj synchronizację żądań), ponieważ przykładowa aplikacja do pralki nie ma interfejsu, który umożliwiałby dodawanie, usuwanie ani zmienianie nazwy pralki. W systemie produkcyjnym musisz wywoływać Request Sync (Poproś o synchronizację) za każdym razem, gdy użytkownik dodaje, usuwa lub zmienia nazwy urządzeń.
Pozostaw włączoną opcję Local Home SDK, ponieważ będziemy testować zarówno ścieżki lokalne, jak i w chmurze.
Aby rozpocząć test, kliknij Dalej: środowisko testowe.

Po zakończeniu testów zobaczysz, że testy wstrzymywania/wznawiania w ścieżce lokalnej kończą się niepowodzeniem, a testy wstrzymywania/wznawiania w ścieżce w chmurze kończą się powodzeniem.

Analizowanie komunikatu o błędzie

Przyjrzyj się bliżej komunikatom o błędach w przypadkach testowych, które zakończyły się niepowodzeniem. Informują one o oczekiwanym i rzeczywistym stanie testu. W tym przypadku w przypadku „Wstrzymaj pralkę” oczekiwany stan to isPaused: true, ale w rzeczywistości otrzymaliśmy isPaused: false. Podobnie w przypadku „Wstrzymaj pralkę” oczekiwany stan to isPaused: true, ale w rzeczywistości otrzymaliśmy isPaused: false.

Z komunikatów o błędach wynika, że w ścieżce lokalnej ustawiamy stan isPaused odwrotnie.

Wykrywanie i naprawianie błędów

Znajdźmy kod źródłowy, w którym aplikacja Home wysyła polecenie wykonania do urządzenia. getDataCommand() to funkcja wywoływana przez executeHandler() w celu ustawienia payload w poleceniu wykonania wysyłanym do urządzenia.

local/index.ts

getDataForCommand(command: string, params: IWasherParams): unknown {
    switch (command) {
        case 'action.devices.commands.OnOff':
            return {
                on: params.on ? true : false
            };
        case 'action.devices.commands.StartStop':
            return {
                isRunning: params.start ? true : false
            };
        case 'action.devices.commands.PauseUnpause':
            return {
                // Is there something wrong here?
                isPaused: params.pause ? false : true
            };
        default:
            console.error('Unknown command', command);
            return {};
    }
}

Ustawiamy isPause w stanie odwrotnym. Powinno być ustawione na true, gdy params.pause ma wartość true, a w pozostałych przypadkach – false. Naprawmy to.

local/index.ts

getDataForCommand(command: string, params: IWasherParams): unknown {
    switch (command) {
        case 'action.devices.commands.OnOff':
            return {
                on: params.on ? true : false
            };
        case 'action.devices.commands.StartStop':
            return {
                isRunning: params.start ? true : false
            };
        case 'action.devices.commands.PauseUnpause':
            return {
                isPaused: params.pause ? true : false
            };
        default:
            console.error('Unknown command', command);
            return {};
    }
}

Zmień wersję aplikacji lokalnego domu, abyśmy mogli sprawdzić, czy używamy właściwej wersji.

local/index.ts

const localHomeSdk = new App('1.0.3');

Pamiętaj, aby ponownie skompilować aplikację i wdrożyć ją w Firebase. W app-faulty/local uruchom:

$ npm run build
$ firebase deploy --only hosting

Teraz zrestartuj urządzenie Google Home, aby mogło załadować zaktualizowaną aplikację lokalnego domu. Sprawdź, czy wersja aplikacji lokalnego domu to 1.0.3.

Testowanie poprawki

Teraz ponownie uruchom zestaw testów dla inteligentnego domu z tymi samymi konfiguracjami. Zobaczysz, że wszystkie przypadki testowe zostały zaliczone.

7. Gratulacje

Gratulacje! Wiesz już, jak rozwiązywać problemy z aplikacją Local Home za pomocą zestawu testów dla inteligentnego domu i Cloud Logging.

Więcej informacji

Oto kilka dodatkowych rozwiązań, które możesz wypróbować:

Dodaj do urządzenia więcej obsługiwanych cech i przeprowadź testy za pomocą pakietu Test Suite.
Dodaj więcej logów niestandardowych w każdym z programów obsługi intencji i wyświetl je w Cloud Logging.
Twórz panele, konfiguruj alerty i uzyskuj dostęp do danych o danych pomiarowych za pomocą interfejsu API, aby otrzymywać przydatne dane o użyciu integracji.

Możesz też dowiedzieć się więcej o testowaniu i przesyłaniu integracji do sprawdzenia, w tym o procesie certyfikacji, który umożliwia opublikowanie integracji dla użytkowników.

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

1. Zanim zaczniesz

Wymagania wstępne

Co utworzysz

Czego się nauczysz

Czego potrzebujesz

2. Uruchamianie aplikacji pralki

Pobieranie kodu źródłowego

Informacje o projekcie

Łączenie Analytics z Firebase

Wdrażanie w Firebase

Aktualizowanie HomeGraph

3. Uruchom inteligentną pralkę

Uruchom urządzenie

4. Testowanie aplikacji Local Home

5. Debugowanie aplikacji Local Home

Łączenie Narzędzi deweloperskich w Chrome

Uruchamianie inspektora

Dodawanie niestandardowych logów

Otwieranie Cloud Logging

Korzystanie z filtrów zaawansowanych

Naprawianie błędu

Testowanie poprawki

6. Uruchamianie pakietu testów dla inteligentnego domu

Uruchamianie zestawu testów dla inteligentnego domu

Analizowanie komunikatu o błędzie

Wykrywanie i naprawianie błędów

Testowanie poprawki

7. Gratulacje

Więcej informacji

Debugowanie lokalnego domu