Fehlerbehebung beim lokalen Zuhause

1. Hinweis

Mit Smart-Home-Integrationen kann Google Assistant verbundene Geräte im Zuhause der Nutzer steuern. Zum Erstellen einer Smart-Home-Aktion müssen Sie einen Cloud-Webhook-Endpunkt bereitstellen, der Smart-Home-Intents verarbeiten kann. Wenn ein Nutzer beispielsweise „Hey Google, schalte das Licht an“ sagt, sendet Assistant den Befehl an Ihre Cloud-Auftragsausführung, um den Gerätestatus zu aktualisieren.

Das Local Home SDK optimiert die Smart-Home-Integration. Es fügt einen lokalen Pfad hinzu, über den Smart-Home-Intents direkt an ein Google Home-Gerät weitergeleitet werden können. Das erhöht die Zuverlässigkeit und verringert die Latenz bei der Verarbeitung von Nutzerbefehlen. Sie können damit eine lokale App für die Auftragsausführung in TypeScript oder JavaScript schreiben und bereitstellen, die Geräte identifiziert und Befehle auf allen intelligenten Lautsprechern oder Smart Displays von Google Home oder Google Nest ausführt. Ihre App kommuniziert dann über das Local Area Network direkt mit den vorhandenen Smart-Home-Geräten der Nutzer und verwendet dazu vorhandene Standardprotokolle zur Ausführung von Befehlen.

72ffb320986092c.png

Das Debuggen von Smart-Home-Aktionen ist ein wichtiger Schritt, um deine Aktionen in Produktionsqualität zu erstellen. Ohne informative und nutzerfreundliche Tools zur Fehlerbehebung und Tests ist es jedoch eine Herausforderung und zeitaufwendig. Mit den Messwerten der Google Cloud Platform (GCP) und Logging sowie der Test-Suite für Smart Home kannst du Probleme bei deinen Aktionen leichter erkennen und beheben.

Voraussetzungen

Aufgaben

In diesem Codelab erstellen Sie eine lokale Ausführung für Smart-Home-Aktionen und verbinden sie mit Assistant. Anschließend debuggen Sie die Local Home App über die Test-Suite für Messwerte und Logging von Smart Homes und Google Cloud Platform (GCP).

Lerninhalte

  • GCP-Messwerte und Logging verwenden, um Produktionsprobleme zu erkennen und zu beheben
  • Anleitung zur Verwendung der Test-Suite zum Erkennen von Funktions- und API-Problemen
  • Hier erfährst du, wie du die Chrome-Entwicklertools bei der Entwicklung der Local Home App verwendest.

Voraussetzungen

2. Waschmaschine-App ausführen

Quellcode abrufen

Klicken Sie auf den folgenden Link, um das Beispiel für dieses Codelab auf Ihren Entwicklungscomputer 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 Start-App enthält ähnliche Unterverzeichnisse und Cloud-Funktionen wie im Codelab Lokale Auftragsausführung für Smart-Home-Aktionen aktivieren. Aber statt app-start haben wir hier app-faulty. Wir beginnen mit einer lokalen Home-App, die funktioniert, aber nicht so gut.

Mit Firebase verbinden

Wir verwenden dasselbe Projekt, das Sie im Codelab Lokale Auftragsausführung für Smart-Home-Aktionen aktivieren erstellt haben. Allerdings stellen wir die in diesem Codelab heruntergeladenen Dateien bereit.

Rufen Sie das Verzeichnis app-faulty auf und richten Sie die Firebase CLI mit dem Actions-Projekt ein, das Sie im Codelab Lokale Auftragsausführung für Smart-Home-Aktionen aktivieren erstellt haben:

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

In Firebase bereitstellen

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

$ cd functions
$ npm install

Hinweis:Wenn die Meldung unten angezeigt wird, können Sie die Meldung ignorieren und fortfahren. Die Warnung ist auf ältere Abhängigkeiten zurückzuführen. Weitere Informationen finden Sie hier.

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 Quelle index.ts (TypeScript) kompiliert und der folgende Inhalt wird im Verzeichnis app-faulty/public/local-home/ platziert:

  • bundle.js: Kompilierte JavaScript-Ausgabe mit der lokalen App und den Abhängigkeiten
  • index.html: Lokale Hostingseite, auf der die App für On-Device-Tests bereitgestellt wird.

Nachdem Sie nun die Abhängigkeiten installiert und Ihr Projekt konfiguriert haben, können Sie die Anwendung 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 werden eine Webanwendung sowie mehrere Cloud Functions for Firebase-Funktionen bereitgestellt.

HomeGraph aktualisieren

Öffnen Sie die Hosting-URL im Browser (https://<project-id>.web.app), um die Web-App aufzurufen. Klicken Sie in der Web-UI auf die Schaltfläche Aktualisierenae8d3b25777a5e30.png, um HomeGraph über Synchronisierung anfordern mit den neuesten Gerätemetadaten aus der fehlerhaften Waschmaschine-App zu aktualisieren:

fa3c47f293cfe0b7.png

Öffnen Sie die Google Home App und prüfen Sie, ob die Waschmaschine mit dem neuen Namen „Fehlerhafte Waschmaschine“ angezeigt wird. Denken Sie daran, das Gerät einem Raum zuzuweisen, in dem sich ein Nest-Gerät befindet.

2a082ee11d47ad1a.png

3. Intelligente Waschmaschine starten

Wenn Sie das Codelab Lokale Auftragsausführung für Smart-Home-Aktionen aktivieren ausgeführt haben, sollten Sie die virtuelle Waschmaschine bereits gestartet haben. Wenn er angehalten wird, denken Sie daran, das virtuelle Gerät neu zu starten.

Gerät starten

Wechseln Sie zum Verzeichnis virtual-device/, führen Sie das Geräteskript aus und ü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

Sie können über Sprachbefehle Befehle an Ihr Gerät senden, z. B.:

„Hey Google, schalte meine Waschmaschine ein.“

„Hey Google, starte meine Waschmaschine.“

„Hey Google, erzwinge die Lokalisierung.“

„Hey Google, halte die Waschmaschine an.“

Sie werden feststellen, dass Google Assistant mit „Tut mir leid, anscheinend ist die defekte Waschmaschine ist im Moment nicht verfügbar“ antwortet, wenn Sie versuchen, die Waschmaschine zu steuern, nachdem Sie „Lokalisierung erzwingen“ aktiviert haben.

Das bedeutet, dass das Gerät nicht über einen lokalen Pfad erreichbar ist. Es hat vor der Ausgabe „Hey Google, lokal erzwingen“ funktioniert, da wir auf den Cloud-Pfad zurückgreifen werden, wenn das Gerät nicht über einen lokalen Pfad erreichbar ist. Nach der Einstellung „Lokalisierung erzwingen“ wird die Option zum Rückgängigmachen des Cloud-Pfads jedoch deaktiviert.

Um das Problem zu finden, nutzen wir unsere Tools: Messwerte der Google Cloud Platform (GCP), Logging und 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 Konsolenprotokolle ansehen und Fehler in der Local Home App beheben. Sie können auch benutzerdefinierte Protokolle an Cloud Logging senden, damit Sie die häufigsten Fehler erkennen, die Nutzer in Ihrer Local Home App finden.

Chrome-Entwicklertools verbinden

So verbinden Sie den Debugger mit Ihrer lokalen Auftragsausführungs-App:

  1. Sie müssen Ihr Google Home-Gerät mit einem Nutzer verknüpft haben, der über die Berechtigung für den Zugriff auf das Projekt Actions Console verfügt.
  2. Starten Sie Ihr Google Home-Gerät neu. Dadurch kann es die URL Ihres HTML-Codes und die Scan-Konfiguration abrufen, die Sie in der Actions Console festgelegt haben.
  3. Starten Sie Chrome auf Ihrem Entwicklungscomputer.
  4. Öffnen Sie einen neuen Chrome-Tab und geben Sie chrome://inspect in das Adressfeld ein, um den Inspector zu starten.

Auf der Seite sollten Sie eine Liste mit Geräten sehen und Ihre App-URL sollte unter dem Namen Ihres Google Home-Geräts angezeigt werden.

567f97789a7d8846.png

Inspector starten

Klicken Sie unter der App-URL auf Prüfen, um die Chrome-Entwicklertools zu starten. Wählen Sie den Tab Console aus und überprüfen Sie, ob Sie den Inhalt des Intents IDENTIFY sehen können, der von Ihrer TypeScript-App gedruckt wurde.

774c460c59f9f84a.png

Diese Ausgabe bedeutet, dass der IDENTIFY-Handler erfolgreich ausgelöst wurde, aber der im IdentifyResponse zurückgegebene verificationId mit keinem der Geräte in HomeGraph übereinstimmt. Lassen Sie uns einige benutzerdefinierte Logs hinzufügen, um den Grund herauszufinden.

Benutzerdefinierte Logs hinzufügen

Das Local Home SDK gibt zwar einen DEVICE_VERIFICATION_FAILED-Fehler aus, hilft aber nicht viel bei der Suche nach der Ursache. Fügen wir einige benutzerdefinierte Logs hinzu, um sicherzustellen, dass die Scandaten korrekt gelesen und verarbeitet werden. Wenn wir das Promise mit einem Fehler ablehnen, wird die Fehlermeldung tatsächlich 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);
}

Ändern Sie auch die Version der lokalen 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 noch einmal in Firebase bereitstellen.

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

Starten Sie nun Ihr Google Home-Gerät neu, damit die aktualisierte lokale Home App geladen werden kann. In den Konsolenprotokollen in den Chrome-Entwicklertools können Sie sehen, ob das Google Home-Gerät die erwartete Version verwendet.

ecc56508ebcf9ab.png

Auf Cloud Logging zugreifen

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

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

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

Erweiterte Filter verwenden

Im Intent IDENTIFY treten Fehler auf, da der lokale Pfad nicht funktioniert, weil das lokale Gerät nicht identifiziert werden kann. Da wir jedoch genau wissen möchten, worin das Problem besteht, filtern wir zuerst die Fehler heraus, die im IDENTIFY-Handler auftreten.

Maximieren Sie das Feld Abfragevorschau. Es sollte sich nun in Query Builder verwandeln. Geben Sie jsonPayload.intent="IDENTIFY" in das Feld Query Builder ein und klicken Sie auf die Schaltfläche Abfrage ausführen.

4c0b9d2828ee2447.png

Infolgedessen erhalten Sie alle Fehlerlogs, die im IDENTIFY-Handler ausgegeben werden. Maximieren Sie als Nächstes den letzten Fehler. Sie finden das errorCode und das debugString, die Sie gerade festgelegt haben, wenn Sie das Promise im IDENTIFY-Handler ablehnen.

71f2f156c6887496.png

An dem debugString können wir erkennen, 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 gefolgt von drei Ziffern beginnt. Die lokale Geräte-ID hier ist jedoch ein Hex-String.

Fehler beheben

Im Quellcode, in dem wir die lokale Geräte-ID aus den Scandaten parsen, stellen wir fest, dass wir beim Konvertieren des Strings in Byte keine Codierung angegeben haben. Die Scandaten werden als hexadezimaler String empfangen. Übergeben Sie daher beim Aufrufen von Buffer.from() hex als Zeichencodierung.

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

Ändern Sie auch die Version der lokalen 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

Fehlerbehebung testen

Starten Sie Ihr Google Home-Gerät nach der Bereitstellung neu, damit die aktualisierte lokale Home App geladen werden kann. Achten Sie darauf, dass die Version 1.0.2 der lokalen Home App ist. Dieses Mal sollten in der Entwicklertools-Konsole von Chrome keine Fehler angezeigt werden.

c8456f7b5f77f894.png

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

„Hey Google, erzwinge die Lokalisierung.“

„Hey Google, halte die Waschmaschine an.“

„Hey Google, schalte meine Waschmaschine ein.“

...

„Hey Google, Standard erzwingen.“

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

Nachdem du dein Gerät über die Touchbedienung in der Google Home App oder per Sprachbefehl bestätigt hast, kannst du mit der automatisierten Test-Suite für Smart Home Anwendungsfälle basierend auf den Gerätetypen und Eigenschaften prüfen, die mit deiner Aktion verknüpft sind. Die Test-Suite führt eine Reihe von Tests durch, um Probleme in deiner Aktion zu erkennen, und zeigt informative Meldungen für fehlgeschlagene Testläufe an, um die Fehlerbehebung zu beschleunigen, bevor die Ereignisprotokolle analysiert werden.

Test-Suite für Smart Home ausführen

So testest du deine Smart-Home-Aktion der Test-Suite:

  1. Öffnen Sie in Ihrem Webbrowser die Test-Suite für Smart Home.
  2. Melden Sie sich über die Schaltfläche oben rechts in Google an. Dadurch kann die Test-Suite die Befehle direkt an Google Assistant senden.
  3. Gib im Feld Projekt-ID die Projekt-ID deiner Smart-Home-Aktion ein. Klicken Sie dann auf WEITER, um fortzufahren.
  4. Im Schritt Testeinstellungen sollte im Abschnitt Geräte und Geräte die fehlerhafte Waschmaschine angezeigt werden.
  5. Deaktivieren Sie die Option Synchronisierung der Testanfrage synchronisieren, da die Beispiel-Waschmaschine keine Benutzeroberfläche hat, um die Waschmaschine hinzuzufügen, zu entfernen oder umzubenennen. In einem Produktionssystem muss die Synchronisierung anfordern immer ausgelöst werden, wenn der Nutzer Geräte hinzufügt, entfernt oder umbenennt.
  6. Lassen Sie die Option Local Home SDK aktiviert, da wir sowohl lokale als auch Cloud-Pfade testen.
  7. Klicken Sie auf WEITER, um mit der Ausführung des Tests zu beginnen.

67433d9190fa770e.png

Wenn die Tests abgeschlossen sind, werden Sie feststellen, dass die Tests zum Pausieren/Fortsetzen im lokalen Pfad scheitern, während die Tests zum Pausieren/Fortsetzen im Cloudpfad bestanden werden.

d1ebd5cfae2a2a47.png

Fehlermeldung analysieren

Sehen Sie sich die Fehlermeldungen in den fehlgeschlagenen Testläufen genauer an. Sie geben an, was der erwartete Zustand für diesen Test ist und wie der tatsächliche Zustand ist. In diesem Fall ist der erwartete Status für „Waschmaschine pausieren“ isPaused: true, aber für den tatsächlichen Status wurde isPaused: false zurückgegeben. Ähnlich ist der erwartete Status für „Waschmaschine pausieren“ isPaused: true, aber für den tatsächlichen Status wurde isPaused: false zurückgegeben.

6bfd3acef9c16b84.png

In den Fehlermeldungen sieht es so aus, als ob wir im lokalen Pfad den Status isPaused umgekehrt hätten.

Fehler identifizieren und beheben

Sehen wir uns den Quellcode an, an den 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 {};
    }
}

isPause wird in der Tat im umgekehrten Zustand festgelegt. Es sollte auf true gesetzt werden, wenn params.pause gleich true ist, andernfalls false. Das sollten wir ändern.

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

Ändern Sie die Version der lokalen 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 noch einmal in Firebase bereitzustellen. Führen Sie in app-faulty/local Folgendes aus:

$ npm run build
$ firebase deploy --only hosting

Starten Sie nun Ihr Google Home-Gerät neu, damit die aktualisierte lokale Home App geladen werden kann. Achten Sie darauf, dass die Version 1.0.3 der lokalen Home App lautet.

Fehlerbehebung testen

Wenn Sie die Testsuite für Smart Home jetzt mit denselben Konfigurationen noch einmal ausführen, werden Sie feststellen, dass alle Testläufe bestanden wurden.

b7fc8c5d3c727d8d.png

7. Glückwunsch

764dbc83b95782a.png

Glückwunsch! Du hast gelernt, wie du mithilfe der Test-Suite für Smart Home und Cloud Logging Fehler mit einer Local Home App beheben kannst.

Weitere Informationen

Außerdem können Sie Folgendes ausprobieren:

Weitere Informationen zum Testen und Einreichen einer Aktion zur Überprüfung sowie zum Zertifizierungsprozess für die Veröffentlichung deiner Aktion für Nutzer