1. Hinweis
Mit Smart-Home-Integrationen kann Google Assistant verbundene Geräte in den Häusern der Nutzer steuern. Wenn Sie eine Cloud-to-Cloud-Integration erstellen möchten, müssen Sie einen Cloud-Webhook-Endpunkt angeben, der Smart-Home-Intents verarbeiten kann. Wenn ein Nutzer beispielsweise „Hey Google, schalte das Licht an“ sagt, sendet Assistant den Befehl an Ihre Cloud-Ausführung, um den Status des Geräts zu aktualisieren.
Das Local Home SDK verbessert Ihre Smart-Home-Integration, indem es einen lokalen Pfad hinzufügt, um Smart-Home-Intents direkt an ein Google Home-Gerät weiterzuleiten. Dadurch wird die Zuverlässigkeit erhöht und die Latenz bei der Verarbeitung von Nutzerbefehlen verringert. Sie können eine lokale Ausführungs-App in TypeScript oder JavaScript schreiben und bereitstellen, die Geräte identifiziert und Befehle auf jedem Google Home-Smart Speaker 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, indem sie vorhandene Standardprotokolle verwendet, um Befehle auszuführen.

Das Debugging von Cloud-to-Cloud-Integrationen ist ein wichtiger Schritt, um Integrationen in Produktionsqualität zu erstellen. Ohne informative, benutzerfreundliche Tools zur Fehlerbehebung und zum Testen ist es jedoch schwierig und zeitaufwendig. Um das Debugging von Cloud-to-Cloud-Integrationen zu erleichtern, stehen Google Cloud Platform (GCP) Messwerte und Logging sowie die Test Suite für Smart Home zur Verfügung, mit denen Sie Probleme mit Ihren Integrationen erkennen und beheben können.
Vorbereitung
- Entwicklerleitfaden für Cloud-to-Cloud-Integrationen erstellen
- Codelab „Lokale Ausführung für Cloud-to-Cloud-Integrationen aktivieren“ ausführen
Aufgaben
In diesem Codelab erstellen Sie eine lokale Ausführung für Cloud-to-Cloud-Integrationen und verbinden sie mit Assistant. Anschließend beheben Sie Fehler in der Local Home App mit der Test Suite für Smart Home und Google Cloud Platform (GCP)-Messwerten und ‑Logging.
Lerninhalte
- Verwendung von GCP-Messwerten und ‑Logging zum Erkennen und Beheben von Produktionsproblemen
- Verwendung der Test Suite zum Erkennen von Funktions- und API-Problemen
- Verwendung der Chrome Dev Tools bei der Entwicklung Ihrer Local Home App
Voraussetzungen
- Die neueste Version von Google Chrome
- Ein iOS- oder Android-Gerät mit der Google Home App
- Ein Google Home-Smart Speaker oder ein Google Nest-Smart Display
- Node.js, Version 24 oder höher
- Ein Google-Konto
- Ein Google Cloud Abrechnungskonto
2. Waschmaschinen-App ausführen
Quellcode abrufen
Klicken Sie auf den folgenden Link, um das Beispiel für dieses Codelab auf Ihren Entwicklungscomputer herunterzuladen:
Alternativ können Sie 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 Functions wie das Codelab Lokale Ausführung für Cloud-to-Cloud-Integrationen aktivieren. Anstelle von app-start haben wir hier jedoch app-faulty. Wir beginnen mit einer Local Home App, die funktioniert, aber nicht sehr 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, stellen aber die in diesem Codelab heruntergeladenen Dateien bereit.
Rufen Sie das Verzeichnis app-faulty auf und richten Sie die 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
Rufen Sie den Ordner app-faulty/functions auf und installieren Sie alle erforderlichen Abhängigkeiten mit npm:
$ cd functions $ npm install
Hinweis:Wenn die folgende Meldung angezeigt wird, können Sie sie ignorieren und fortfahren. Die Warnung ist auf einige ä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
Rufen Sie das Verzeichnis app-faulty/local/ auf 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 die folgenden Inhalte werden 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: Lokale Hosting-Seite, 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 Webanwendung 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 Webanwendung aufzurufen. Klicken Sie auf der Web-UI auf die Schaltfläche Aktualisieren
, um HomeGraph mit den neuesten Gerätemetadaten aus der fehlerhaften Waschmaschinen-App zu aktualisieren. Verwenden Sie dazu Synchronisierung anfordern.

Öffnen Sie die Google Home App und prüfen Sie, ob Ihre Waschmaschine mit dem neuen Namen „Faulty Washer“ angezeigt wird. Weisen Sie das Gerät einem Raum zu, in dem sich ein Nest-Gerät befindet.

3. Smart-Waschmaschine starten
Wenn Sie das Codelab Lokale Ausführung für Cloud-to-Cloud-Integrationen aktivieren ausgeführt haben, sollten Sie die virtuelle Smart-Waschmaschine bereits gestartet haben. Wenn sie angehalten wurde, starten Sie das virtuelle Gerät neu.
Gerät starten
Rufen Sie das Verzeichnis virtual-device/ auf 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
Senden Sie Befehle an Ihr Gerät über Sprachbefehle an das Google Home-Gerät, z. B.:
„Hey Google, schalte meine Waschmaschine ein.“
„Hey Google, starte meine Waschmaschine.“
„Hey Google, erzwinge lokal.“
„Hey Google, halte meine Waschmaschine an.“
Google Assistant antwortet mit „Tut mir leid, die fehlerhafte Waschmaschine ist derzeit nicht verfügbar“, wenn Sie versuchen, die Waschmaschine nach „erzwinge lokal“ zu steuern.
Das bedeutet, dass das Gerät nicht über einen lokalen Pfad erreichbar ist. Vor dem Befehl „Hey Google, erzwinge lokal“ hat es funktioniert, weil wir auf den Cloud-Pfad zurückgreifen, wenn das Gerät nicht über einen lokalen Pfad erreichbar ist. Nach „erzwinge lokal“ 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 und 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 Fehler in der Local Home App beheben. Sie können auch benutzerdefinierte Logs an Cloud Logging senden, damit Sie über die häufigsten Fehler informiert sind, die Nutzer in Ihrer Local Home App finden.
Chrome-Entwicklertools verbinden
So verbinden Sie den Debugger mit Ihrer lokalen Ausführungs-App:
- Verknüpfen Sie Ihr Google Home-Gerät mit einem Nutzer, der die Berechtigung hat, auf das Developer Console-Projekt zuzugreifen.
- Starten Sie Ihr Google Home-Gerät neu. Dadurch kann es die URL Ihres HTML sowie die Scankonfiguration abrufen, die Sie in der Developer Console eingegeben haben.
- Starten Sie Chrome auf Ihrem Entwicklungscomputer.
- Öffnen Sie einen neuen Chrome-Tab und geben Sie
chrome://inspectin das Adressfeld ein, um das Prüftool zu starten.
Auf der Seite sollte eine Liste der Geräte angezeigt werden. Die App-URL sollte unter dem Namen Ihres Google Home-Geräts zu sehen sein.

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

Diese Ausgabe bedeutet, dass der IDENTIFY-Handler erfolgreich ausgelöst wurde, die in der IdentifyResponse zurückgegebene verificationId jedoch mit keinem der Geräte in Ihrem HomeGraph übereinstimmt. Wir fügen einige benutzerdefinierte Logs hinzu, um herauszufinden, warum.
Benutzerdefinierte Logs hinzufügen
Obwohl das Local Home SDK einen DEVICE_VERIFICATION_FAILED-Fehler ausgibt, hilft das nicht viel bei der Ermittlung der Ursache. Wir fügen einige benutzerdefinierte Logs hinzu, um sicherzustellen, dass wir die Scandaten korrekt 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);
}
Ändern Sie 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
Starten Sie jetzt Ihr Google Home-Gerät neu, damit die aktualisierte Local Home App geladen werden kann. Sie können prüfen, ob das Google Home-Gerät die erwartete Version verwendet, indem Sie sich die Konsolenlogs in den Chrome-Entwicklertools ansehen.

Auf Cloud Logging zugreifen
Sehen wir uns an, wie Sie mit Cloud Logging Fehler finden können. So greifen Sie auf Cloud Logging für Ihr Projekt zu:
- Wechseln Sie in der Cloud Console zur Seite Projekte.
- 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 access control.
Erweiterte Filter verwenden
Wir wissen, dass im IDENTIFY-Intent Fehler auftreten, da der lokale Pfad nicht funktioniert, weil das lokale Gerät nicht identifiziert werden kann. Wir möchten jedoch genau wissen, was das Problem ist. Filtern wir zuerst die Fehler heraus, die im IDENTIFY-Handler auftreten.
Klicken Sie auf den Umschalter Abfrage anzeigen. Er sollte sich in ein Feld Query Builder verwandeln. Geben Sie jsonPayload.intent="IDENTIFY" in das Feld Query Builder ein und klicken Sie auf die Schaltfläche Abfrage ausführen.

Als Ergebnis erhalten Sie alle Fehlerlogs, die im IDENTIFY-Handler ausgelöst werden. Maximieren Sie als Nächstes den letzten Fehler. Sie finden die errorCode und debugString, die Sie gerade beim Ablehnen des Promise im IDENTIFY-Handler festgelegt haben.

Aus dem debugString können wir erkennen, dass die lokale Geräte-ID nicht im erwarteten Format ist. Die Local Home App erwartet die lokale Geräte-ID als String, der mit deviceid beginnt und von drei Ziffern gefolgt wird. Die lokale Geräte-ID ist hier jedoch ein Hex-String.
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 nicht angegeben haben, als wir den String in Byte umgewandelt haben. Die Scandaten werden als Hex-String 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);
}
Ändern Sie 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
Starten Sie nach der Bereitstellung Ihr Google Home-Gerät 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 Konsole der Chrome-Entwicklertools keine Fehler angezeigt werden.

Jetzt können Sie noch einmal versuchen, Befehle an Ihr Gerät zu senden.
„Hey Google, erzwinge lokal.“
„Hey Google, halte meine Waschmaschine an.“
„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 über Sprachbefehle bestätigt haben, können Sie mit der automatisierten Test Suite für Smart Home Anwendungsfälle basierend auf den Gerätetypen und Merkmalen validieren, die mit Ihrer Integration verknüpft sind. Die Test Suite führt eine Reihe von Tests aus, um Probleme in Ihrer Integration zu erkennen. Außerdem werden informative Meldungen für fehlgeschlagene Testfälle angezeigt, damit Sie Fehler schneller beheben können, bevor Sie sich mit Ereignislogs befassen.
Test Suite für Smart Home ausführen
Folgen Sie dieser Anleitung, um Ihre Cloud-to-Cloud-Integration mit der Test Suite zu testen:
- Öffnen Sie in Ihrem Webbrowser die Test Suite für Smart Home.
- Melden Sie sich über die Schaltfläche rechts oben 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-to-Cloud-Integration ein. Klicken Sie dann auf Weiter , um fortzufahren.
- Im Schritt Testeinstellungen sollte Ihre fehlerhafte Waschmaschine im Abschnitt Geräte und Merkmale angezeigt werden.
- Deaktivieren Sie die Option Synchronisierung anfordern testen , da die Beispiel-Waschmaschinen-App keine UI zum Hinzufügen, Entfernen oder Umbenennen der Waschmaschine hat. In einem Produktionssystem müssen Sie Synchronisierung anfordern 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 möchten.
- Klicken Sie auf Weiter: Testumgebung , um den Test auszuführen.

Nach Abschluss der Tests werden Sie feststellen, dass die Tests zum Anhalten/Fortsetzen im lokalen Pfad fehlschlagen, während die Tests zum Anhalten/Fortsetzen im Cloud-Pfad erfolgreich sind.

Fehlermeldung analysieren
Sehen Sie sich die Fehlermeldungen in den fehlgeschlagenen Testfällen genauer an. Sie geben an, welcher Status für diesen Test erwartet wird und welcher Status tatsächlich erreicht wurde. In diesem Fall ist der erwartete Status für „Waschmaschine anhalten“ isPaused: true, aber im tatsächlichen Status haben wir isPaused: false. Ebenso ist der erwartete Status für „Waschmaschine anhalten“ isPaused: true, aber im tatsächlichen Status haben wir isPaused: false.

Aus den Fehlermeldungen geht hervor, dass wir im lokalen Pfad den Status isPaused umgekehrt festlegen.
Fehler erkennen 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 die 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 Status fest. Es sollte auf true gesetzt werden, wenn params.pause true ist, und andernfalls auf false. Beheben wir das.
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 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.3');
Kompilieren Sie die App noch einmal 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
Starten Sie jetzt Ihr Google Home-Gerät neu, damit die aktualisierte Local Home App geladen werden kann. Die Version der Local Home App sollte 1.0.3 sein.
Korrektur testen
Führen Sie die Test Suite für Smart Home jetzt noch einmal mit denselben Konfigurationen aus. Alle Testfälle sollten erfolgreich sein.

7. Glückwunsch

Glückwunsch! Sie haben gelernt, wie Sie Fehler in einer Local Home App mit der Test Suite für Smart Home und Cloud Logging beheben.
Weitere Informationen
Hier sind einige weitere Dinge, die Sie ausprobieren können:
- Fügen Sie Ihrem Gerät weitere unterstützte Merkmale hinzu und testen Sie es mit der Test Suite.
- Fügen Sie in jedem der Intent-Handler weitere benutzerdefinierte Logs hinzu und sehen Sie sie in Cloud Logging an.
- Erstellen Sie Dashboards, richten Sie Benachrichtigungen ein und greifen Sie programmatisch auf Messwertdaten zu, um hilfreiche Nutzungsmesswerte für Ihre Integration zu erhalten.
Weitere Informationen zum Testen und Einreichen einer Integration zur Überprüfung, einschließlich des Zertifizierungsprozesses zum Veröffentlichen Ihrer Integration für Nutzer