Die Migration zum Google Home Developer Center ist abgeschlossen.

Fehlerbehebung beim lokalen Zuhause

1. Hinweis

Mit Smart-Home-Integrationen kann Google Assistant verbundene Geräte in den Wohnungen der Nutzer steuern. Um eine Cloud-zu-Cloud-Integration zu erstellen, müssen Sie einen Cloud-Webhook-Endpunkt angeben, der Smart Home-Intents verarbeiten kann. Wenn ein Nutzer beispielsweise „Hey Google, schalte das Licht ein“ sagt, sendet Assistant den Befehl an deine Cloud-Ausführung, um den Status des Geräts zu aktualisieren.

Das Local Home SDK optimiert Ihre Smart-Home-Integration, indem es einen lokalen Pfad hinzufügt, über den Smart Home-Intents direkt an ein Google Home-Gerät weitergeleitet werden. Dadurch wird die Zuverlässigkeit verbessert und die Latenz bei der Verarbeitung von Nutzerbefehlen verringert. Damit können Sie eine lokale Ausführungs-App in TypeScript oder JavaScript schreiben und bereitstellen, die Geräte identifiziert und Befehle auf einem beliebigen Google Home-Smart-Lautsprecher oder Google Nest-Smart-Display ausführt. Ihre App kommuniziert dann direkt über das lokale Netzwerk mit den vorhandenen Smart-Home-Geräten der Nutzer, um Befehle mithilfe vorhandener Standardprotokolle auszuführen.

Das Debuggen von Cloud-zu-Cloud-Integrationen ist ein wichtiger Schritt, um Integrationen in Produktionsqualität zu erstellen. Ohne informative, benutzerfreundliche Tools zur Fehlerbehebung und zum Testen ist dies jedoch schwierig und zeitaufwendig. Um das Debugging von Cloud-to-Cloud-Integrationen zu erleichtern, sind Messwerte und Logging von Google Cloud Platform (GCP) sowie die Testsuite für Smart Home verfügbar, mit denen Sie Probleme bei Ihren Integrationen identifizieren und beheben können.

Vorbereitung

Entwicklerleitfaden zum Erstellen einer Cloud-zu-Cloud-Integration
Führen Sie das Codelab Lokale Ausführung für Cloud-zu-Cloud-Integrationen aktivieren aus.

Aufgaben

In diesem Codelab erstellen Sie eine lokale Ausführung für Cloud-zu-Cloud-Integrationen und verbinden sie mit Assistant. Anschließend beheben Sie Fehler in der Local Home-App mithilfe der Testsuite für Smart Home sowie GCP-Messwerte und ‑Logging.

Lerninhalte

So verwenden Sie GCP-Messwerte und ‑Logging, um Produktionsprobleme zu identifizieren und zu beheben.
So verwenden Sie die Test Suite, um Funktions- und API-Probleme zu erkennen.
So verwenden Sie die Chrome-Entwicklertools bei der Entwicklung Ihrer Local Home-App.

Voraussetzungen

Die aktuelle Version von Google Chrome
Ein iOS- oder Android-Gerät mit der Google Home App
Einen Google Home-Smart-Lautsprecher oder ein Google Nest Smart Display
Node.js-Version 10.16 oder höher
Ein Google-Konto
Ein Google Cloud-Rechnungskonto

2. Waschmaschinen-App ausführen

Quellcode abrufen

Klicken Sie auf den folgenden Link, um das Beispiel für dieses Codelab auf Ihren Entwicklercomputer herunterzuladen:

… oder Sie können das GitHub-Repository über die Befehlszeile klonen:

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

Über das Projekt

Die Starter-App enthält ähnliche Unterverzeichnisse und Cloud-Funktionen wie das Codelab Lokale Auftragsausführung für Cloud-zu-Cloud-Integrationen aktivieren. Statt app-start haben wir hier aber app-faulty. Wir beginnen mit einer lokalen Home-App, die funktioniert, aber nicht so gut.

Mit Firebase verknüpfen

Wir verwenden dasselbe Projekt, das Sie im Codelab Lokale Ausführung für Cloud-to-Cloud-Integrationen aktivieren erstellt haben. Wir stellen jedoch die in diesem Codelab heruntergeladenen Dateien bereit.

Rufen Sie das Verzeichnis app-faulty auf und richten Sie dann das Firebase CLI mit Ihrem Integrationsprojekt ein, das Sie im Codelab Lokale Ausführung für Cloud-to-Cloud-Integrationen aktivieren erstellt haben:

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

In Firebase bereitstellen

Wechseln Sie zum Ordner app-faulty/functions und installieren Sie alle erforderlichen Abhängigkeiten mit npm:

$ cd functions
$ npm install

Hinweis:Wenn Sie die folgende Meldung sehen, können Sie sie ignorieren und fortfahren. Die Warnung wird aufgrund einiger älterer Abhängigkeiten angezeigt. Weitere Informationen

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

Wechseln Sie zum Verzeichnis app-faulty/local/ und führen Sie die folgenden Befehle aus, um den TypeScript-Compiler herunterzuladen und die App zu kompilieren:

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

Dadurch wird die index.ts-Quelle (TypeScript) kompiliert und der folgende Inhalt in das Verzeichnis app-faulty/public/local-home/ eingefügt:

bundle.js: Kompilierte JavaScript-Ausgabe mit der lokalen App und den Abhängigkeiten.
index.html: Seite für lokales Hosting, die zum Bereitstellen der App für Tests auf dem Gerät verwendet wird.

Nachdem Sie die Abhängigkeiten installiert und Ihr Projekt konfiguriert haben, können Sie die App zum ersten Mal ausführen.

$ firebase deploy

Die Ausgabe der Konsole sollte so aussehen:

...

✔ Deploy complete!

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

Mit diesem Befehl wird eine Web-App zusammen mit mehreren Cloud Functions für Firebase bereitgestellt.

HomeGraph aktualisieren

Öffnen Sie die Hosting-URL in Ihrem Browser (https://<project-id>.web.app), um die Web-App aufzurufen. Klicken Sie in der Weboberfläche auf die Schaltfläche Aktualisieren, um HomeGraph mit den neuesten Gerätemetadaten aus der fehlerhaften Waschmaschinen-App über Request Sync zu aktualisieren.

Öffne die Google Home App und prüfe, ob du deine Waschmaschine mit dem neuen Namen „Defekte Waschmaschine“ sehen kannst. Weise das Gerät einem Raum zu, in dem sich ein Nest-Gerät befindet.

3. Smarte Waschmaschine starten

Wenn Sie das Codelab Lokale Ausführung für Cloud-zu-Cloud-Integrationen aktivieren durchlaufen haben, sollten Sie die virtuelle Smart Washer bereits gestartet haben. Wenn sie beendet wurde, müssen Sie das virtuelle Gerät neu starten.

Gerät starten

Wechseln Sie in das Verzeichnis virtual-device/ und führen Sie das Geräteskript aus. Übergeben Sie die Konfigurationsparameter als Argumente:

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

Prüfen Sie, ob das Geräteskript mit den erwarteten Parametern ausgeführt wird:

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

4. Local Home App testen

Du kannst deinem Gerät über Sprachbefehle an das Google Home-Gerät Befehle senden, z. B.:

„Hey Google, schalte meine Waschmaschine ein.“

„Hey Google, starte meine Waschmaschine.“

„Hey Google, erzwinge lokal.“

„Hey Google, stoppe meine Waschmaschine.“

Wenn Sie versuchen, die Waschmaschine nach „force local“ zu steuern, antwortet Google Assistant mit „Tut mir leid, die fehlerhafte Waschmaschine ist derzeit nicht verfügbar“.

Das bedeutet, dass das Gerät nicht über einen lokalen Pfad erreichbar ist. Vor dem Ausführen von „Hey Google, force local“ hat es funktioniert, weil wir auf den Cloud-Pfad zurückgreifen, wenn das Gerät nicht über einen lokalen Pfad erreichbar ist. Nach „force local“ ist die Option, auf den Cloud-Pfad zurückzugreifen, jedoch deaktiviert.

Um das Problem zu ermitteln, verwenden wir die folgenden Tools: Google Cloud Platform (GCP) Messwerte und Logging sowie die Chrome-Entwicklertools.

5. Fehler in der Local Home-App beheben

Im folgenden Abschnitt verwenden Sie die von Google bereitgestellten Tools, um herauszufinden, warum das Gerät nicht über den lokalen Pfad erreichbar ist. Mit den Google Chrome-Entwicklertools können Sie eine Verbindung zum Google Home-Gerät herstellen, die Konsolenlogs aufrufen und die Local Home-App debuggen. Sie können auch benutzerdefinierte Logs an Cloud Logging senden, um über die häufigsten Fehler informiert zu werden, die Nutzer in Ihrer Local Home-App finden.

Chrome-Entwicklertools verbinden

So stellen Sie eine Verbindung zwischen dem Debugger und Ihrer lokalen Fulfillment-App her:

Achte darauf, dass du dein Google Home-Gerät mit einem Nutzer verknüpft hast, der berechtigt ist, auf das Developer Console-Projekt zuzugreifen.
Starte dein Google Home-Gerät neu. Dadurch kann es die URL deines HTML-Codes sowie die Scan-Konfiguration abrufen, die du in der Developer Console eingegeben hast.
Starten Sie Chrome auf Ihrem Entwicklungscomputer.
Öffnen Sie einen neuen Chrome-Tab und geben Sie chrome://inspect in das Adressfeld ein, um das Tool zu starten.

Auf der Seite sollte eine Liste von Geräten angezeigt werden. Die App-URL sollte unter dem Namen Ihres Google Home-Geräts zu sehen sein.

Inspector starten

Klicken Sie unter der URL Ihrer App auf Untersuchen, um die Chrome-Entwicklertools zu starten. Wählen Sie den Tab Console aus und prüfen Sie, ob Sie den Inhalt des IDENTIFY-Intents sehen, der von Ihrer TypeScript-App ausgegeben wird.

Diese Ausgabe bedeutet, dass der IDENTIFY-Handler erfolgreich ausgelöst wurde, aber der in IdentifyResponse zurückgegebene verificationId stimmt mit keinem der Geräte in Ihrem HomeGraph überein. Fügen wir einige benutzerdefinierte Logs hinzu, um den Grund herauszufinden.

Benutzerdefinierte Logs hinzufügen

Obwohl das Local Home SDK einen DEVICE_VERIFICATION_FAILED-Fehler ausgibt, hilft das nicht viel bei der Suche nach der Ursache. Fügen wir einige benutzerdefinierte Logs hinzu, um sicherzugehen, dass wir die Scandaten richtig lesen und verarbeiten. Wenn wir das Promise mit einem Fehler ablehnen, wird die Fehlermeldung auch an Cloud Logging gesendet.

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);
}

Ändere außerdem die Version der Local Home App, damit wir feststellen können, ob wir die richtige Version verwenden.

local/index.ts

const localHomeSdk = new App('1.0.1');

Nachdem Sie die benutzerdefinierten Logs hinzugefügt haben, müssen Sie die App noch einmal kompilieren und in Firebase bereitstellen.

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

Starte dein Google Home-Gerät neu, damit die aktualisierte Local Home-App geladen werden kann. In den Konsolen-Logs in den Chrome-Entwicklertools kannst du sehen, ob auf dem Google Home-Gerät die erwartete Version verwendet wird.

Auf Cloud Logging zugreifen

Sehen wir uns an, wie Sie Cloud Logging verwenden, um Fehler zu finden. So greifen Sie auf Cloud Logging für Ihr Projekt zu:

Rufen Sie in der Cloud Console die Seite Projekte auf.
Wählen Sie Ihr Smart-Home-Projekt aus.
Wählen Sie unter Vorgänge die Option Logging > Log-Explorer aus.

Der Zugriff auf Logging-Daten wird über Identity and Access Management (IAM) für Nutzer Ihres Integrationsprojekts verwaltet. Weitere Informationen zu Rollen und Berechtigungen für Logging-Daten finden Sie unter Zugriffssteuerung für Cloud Logging.

Erweiterte Filter verwenden

Wir wissen, dass im Intent IDENTIFY Fehler auftreten, da der lokale Pfad nicht funktioniert, weil das lokale Gerät nicht erkannt wird. Wir möchten jedoch genau wissen, was das Problem ist. Filtern wir also zuerst die Fehler heraus, die im IDENTIFY-Handler auftreten.

Klicken Sie auf den Umschalter Abfrage anzeigen. Er sollte sich in das Feld Query Builder verwandeln. Geben Sie jsonPayload.intent="IDENTIFY" in das Feld Query Builder ein und klicken Sie auf den Button Abfrage ausführen.

So erhalten Sie alle Fehlerlogs, die im IDENTIFY-Handler ausgegeben werden. Maximieren Sie als Nächstes den letzten Fehler. Die Werte für errorCode und debugString, die Sie gerade festgelegt haben, finden Sie beim Ablehnen des Promise im IDENTIFY-Handler.

Aus dem debugString geht hervor, dass die lokale Geräte-ID nicht das erwartete Format hat. Die Local Home App erwartet die lokale Geräte-ID als String, der mit deviceid beginnt und dem 3 Ziffern folgen. Die lokale Geräte-ID ist hier jedoch ein Hexadezimalstring.

Fehler beheben

Wenn wir zum Quellcode zurückkehren, in dem wir die lokale Geräte-ID aus den Scandaten parsen, stellen wir fest, dass wir die Codierung beim Konvertieren des Strings in Byte nicht angegeben haben. Die Scandaten werden als Hexadezimalstring empfangen. Übergeben Sie daher hex als Zeichencodierung, wenn Sie Buffer.from() aufrufen.

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);
}

Ändere außerdem die Version der Local Home App, damit wir feststellen können, ob wir die richtige Version verwenden.

local/index.ts

const localHomeSdk = new App('1.0.2');

Nachdem Sie den Fehler behoben haben, kompilieren Sie die App und stellen Sie sie noch einmal in Firebase bereit. Führen Sie in app-faulty/local Folgendes aus:

$ npm run build
$ firebase deploy --only hosting

Korrektur testen

Starte dein Google Home-Gerät nach der Bereitstellung neu, damit die aktualisierte Local Home-App geladen werden kann. Die Version der Local Home-App sollte 1.0.2 sein. Dieses Mal sollten in der Chrome-Entwicklertools-Konsole keine Fehler angezeigt werden.

Jetzt können Sie wieder versuchen, Befehle an Ihr Gerät zu senden.

„Hey Google, erzwinge lokal.“

„Hey Google, stoppe meine Waschmaschine.“

„Hey Google, schalte meine Waschmaschine ein.“

…

„Hey Google, erzwinge Standard.“

6. Test-Suite für Smart Home ausführen

Nachdem Sie Ihr Gerät über die Touchbedienung in der Google Home App oder per Sprachbefehl bestätigt haben, können Sie mit der automatisierten Testsuite für Smart Home Anwendungsfälle basierend auf den Gerätetypen und Attributen validieren, die mit Ihrer Integration verknüpft sind. In der Testsuite werden eine Reihe von Tests ausgeführt, um Probleme in Ihrer Integration zu erkennen. Außerdem werden informative Meldungen für fehlgeschlagene Testläufe angezeigt, damit Sie die Fehlerbehebung beschleunigen können, bevor Sie sich die Ereignisprotokolle ansehen.

Test-Suite für Smart Home ausführen

Folge dieser Anleitung, um deine Cloud-to-Cloud-Integration mit der Test-Suite zu testen:

Öffnen Sie in Ihrem Webbrowser die Test Suite for Smart Home.
Melden Sie sich über die Schaltfläche oben rechts bei Google an. Dadurch kann die Test Suite die Befehle direkt an Google Assistant senden.
Geben Sie im Feld Projekt-ID die Projekt-ID Ihrer Cloud-zu-Cloud-Integration ein. Klicken Sie dann auf Weiter, um fortzufahren.
Im Schritt Testeinstellungen sollte Ihre defekte Waschmaschine im Abschnitt Geräte und Testläufe angezeigt werden.
Deaktiviere die Option Test Request Sync (Testanfrage synchronisieren), da die Beispiel-Waschmaschinen-App keine Benutzeroberfläche zum Hinzufügen, Entfernen oder Umbenennen der Waschmaschine hat. In einem Produktionssystem müssen Sie Request Sync auslösen, wenn der Nutzer Geräte hinzufügt, entfernt oder umbenennt.
Lassen Sie die Option Local Home SDK aktiviert, da wir sowohl lokale als auch Cloud-Pfade testen werden.
Klicken Sie auf Weiter: Testumgebung, um den Test auszuführen.

Nach Abschluss der Tests sehen Sie, dass die Pause-/Fortsetzen-Tests im lokalen Pfad fehlschlagen, während die Pause-/Fortsetzen-Tests im Cloud-Pfad erfolgreich sind.

Fehlermeldung analysieren

Sehen Sie sich die Fehlermeldungen in den fehlgeschlagenen Testläufen genauer an. Sie geben an, welcher Status für den Test erwartet wird und welcher Status tatsächlich vorliegt. In diesem Fall ist der erwartete Status für „Waschmaschine pausieren“ isPaused: true, aber im tatsächlichen Status haben wir isPaused: false erhalten. Ähnlich verhält es sich bei „Waschmaschine pausieren“. Der erwartete Status ist isPaused: true, aber im tatsächlichen Status haben wir isPaused: false erhalten.

Aus den Fehlermeldungen geht hervor, dass wir im lokalen Pfad den Status isPaused umgekehrt festlegen.

Fehler identifizieren und beheben

Suchen wir den Quellcode, in dem die Local Home App den Ausführungsbefehl an das Gerät sendet. getDataCommand() ist die Funktion, die von executeHandler() aufgerufen wird, um payload im Ausführungsbefehl festzulegen, der an das Gerät gesendet wird.

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 {};
    }
}

Wir legen isPause tatsächlich im umgekehrten Zustand fest. Es sollte auf true festgelegt werden, wenn params.pause true ist, und auf false, wenn params.pause false ist. Das beheben wir jetzt.

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 {};
    }
}

Ändere die Version der Local Home-App, damit wir feststellen können, ob wir die richtige Version verwenden.

local/index.ts

const localHomeSdk = new App('1.0.3');

Denken Sie daran, die App noch einmal zu kompilieren und in Firebase bereitzustellen. Führen Sie in app-faulty/local Folgendes aus:

$ npm run build
$ firebase deploy --only hosting

Starte dein Google Home-Gerät neu, damit die aktualisierte Local Home App geladen werden kann. Die Version der Local Home App muss 1.0.3 sein.

Korrektur testen

Führen Sie die Testsuite für Smart Home nun mit denselben Konfigurationen noch einmal aus. Alle Testläufe sollten erfolgreich sein.

7. Glückwunsch

Glückwunsch! Sie haben gelernt, wie Sie eine Local Home-App mit der Test Suite für Smart Home und Cloud Logging Fehler beheben.

Weitere Informationen

Hier sind einige zusätzliche Dinge, die Sie ausprobieren können:

Füge deinem Gerät weitere unterstützte Merkmale hinzu und teste es mit der Test-Suite.
Fügen Sie jedem Intent-Handler weitere benutzerdefinierte Logs hinzu und sehen Sie sie sich in Cloud Logging an.
Sie können Dashboards erstellen, Benachrichtigungen einrichten und programmatisch auf Messwertdaten zugreifen, um hilfreiche Nutzungsmesswerte für Ihre Integration zu erhalten.

Hier finden Sie weitere Informationen zum Testen und Einreichen einer Integration zur Überprüfung, einschließlich des Zertifizierungsprozesses, um Ihre Integration für Nutzer zu veröffentlichen.

Fehlerbehebung beim lokalen Zuhause Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

1. Hinweis

Vorbereitung

Aufgaben

Lerninhalte

Voraussetzungen

2. Waschmaschinen-App ausführen

Quellcode abrufen

Über das Projekt

Mit Firebase verknüpfen

In Firebase bereitstellen

HomeGraph aktualisieren

3. Smarte Waschmaschine starten

Gerät starten

4. Local Home App testen

5. Fehler in der Local Home-App beheben

Chrome-Entwicklertools verbinden

Inspector starten

Benutzerdefinierte Logs hinzufügen

Auf Cloud Logging zugreifen

Erweiterte Filter verwenden

Fehler beheben

Korrektur testen

6. Test-Suite für Smart Home ausführen

Test-Suite für Smart Home ausführen

Fehlermeldung analysieren

Fehler identifizieren und beheben

Korrektur testen

7. Glückwunsch

Weitere Informationen

Fehlerbehebung beim lokalen Zuhause