Lokale Auftragsausführungs-App implementieren

Zur Unterstützung der lokalen Auftragsausführung müssen Sie eine App für die Verarbeitung dieser Smart-Home-Intents erstellen:

• IDENTIFY: Unterstützt die Erkennung von lokal steuerbaren Smart-Home-Geräten. Der Intent-Handler extrahiert Daten, die bei der Erkennung von Ihrem Smart-Home-Gerät zurückgegeben werden, und sendet diese als Antwort an Google.
• EXECUTE: Unterstützt die Ausführung von Befehlen.
• QUERY: Unterstützt die Abfrage des Gerätestatus.
• REACHABLE_DEVICES (optional): Unterstützt die Erkennung von lokal steuerbaren Endgeräten hinter einem Hub (oder Bridge).

Diese App wird auf Google Home- oder Google Nest-Geräten von Nutzern ausgeführt und verbindet dein Smart-Home-Gerät mit Assistant. Sie können die App mit TypeScript (bevorzugt) oder JavaScript erstellen.

TypeScript wird empfohlen, da Sie mithilfe von Bindungen statisch dafür sorgen, dass die von Ihrer Anwendung zurückgegebenen Daten den Typen entsprechen, die die Plattform erwartet.

Weitere Informationen zur API finden Sie in der Referenz zur Local Home SDK API (in englischer Sprache).

Die folgenden Snippets zeigen, wie Sie die Anwendung für die lokale Auftragsausführung initialisieren und Ihre Handler anhängen.

import App = smarthome.App;
const localHomeApp: App = new App("1.0.0");
localHomeApp
  .onIdentify(identifyHandler)
  .onExecute(executeHandler)
  .listen()
  .then(() => {
    console.log("Ready");
  });

import App = smarthome.App;
const localHomeApp: App = new App("1.0.0");
localHomeApp
  .onIdentify(identifyHandler)
  .onReachableDevices(reachableDevicesHandler)
  .onExecute(executeHandler)
  .listen()
  .then(() => {
    console.log("Ready");
  });

Projekt erstellen

Zum Bereitstellen Ihrer lokalen Auftragsausführungs-App müssen Sie ein JavaScript-Bundle für Ihren Code und alle zugehörigen Abhängigkeiten erstellen.

Verwenden Sie die Projekt initialisierte Anwendung für die lokale Auftragsausführung, um die entsprechende Projektstruktur mit Ihrer bevorzugten Bundler-Konfiguration zu starten.

Projektvorlagen

Führen Sie zum Auswählen der Bundler-Konfiguration den Befehl npm init aus, wie in den folgenden Beispielen gezeigt:

npm init @google/local-home-app project-directory/ --bundler none

project-directory/
├── node_modules/
├── package.json
├── .gitignore
├── index.ts
├── test.ts
├── tsconfig.json
├── tslint.json
└── serve.js

npm init @google/local-home-app project-directory/ --bundler webpack

project-directory/
├── node_modules/
├── package.json
├── .gitignore
├── index.ts
├── test.ts
├── tsconfig.json
├── tslint.json
├── webpack.config.web.js
├── webpack.config.node.js
└── serve.js

npm init @google/local-home-app project-directory/ --bundler rollup

project-directory/
├── node_modules/
├── package.json
├── .gitignore
├── index.ts
├── test.ts
├── tsconfig.json
├── tslint.json
├── rollup.config.js
└── serve.js

npm init @google/local-home-app project-directory/ --bundler parcel

project-directory/
├── node_modules/
├── package.json
├── .gitignore
├── index.ts
├── test.ts
├── tsconfig.json
├── tslint.json
└── serve.js

Allgemeine Aufgaben auf Projektebene ausführen

Das generierte Projekt unterstützt die folgenden npm-Skripts:

cd project-directory/
npm run build

cd project-directory/
npm run lint
npm run compile
npm test

cd project-directory/
npm run start

IDENTIFY-Handler implementieren

Der IDENTIFY-Handler wird ausgelöst, wenn das Google Home- oder Google Nest-Gerät neu gestartet wird und nicht bestätigte lokale Geräte (einschließlich Endgeräten, die mit einem Hub verbunden sind) erkannt werden. Die Local Home-Plattform sucht anhand der zuvor angegebenen Informationen der Scankonfiguration nach lokalen Geräten und ruft den Handler IDENTIFY mit den Scanergebnissen auf.

Der IdentifyRequest von der lokalen Startseitenplattform enthält die Scandaten einer LocalIdentifiedDevice-Instanz. Basierend auf der Scankonfiguration, die das Gerät erkannt hat, wird nur eine device-Instanz befüllt.

Wenn die Scanergebnisse mit Ihrem Gerät übereinstimmen, sollte der IDENTIFY-Handler ein IdentifyResponsePayload-Objekt zurückgeben, das ein device-Objekt mit Smart-Home-Metadaten (z. B. Typen, Eigenschaften und Berichtsstatus) enthält.

Google stellt eine Geräteverknüpfung her, wenn verificationId aus der IDENTIFY-Antwort mit einem der otherDeviceIds-Werte übereinstimmt, die von der SYNC-Antwort zurückgegeben werden.

Beispiel

Die folgenden Snippets zeigen, wie Sie IDENTIFY-Handler für eigenständige Geräte- bzw. Hub-Integrationen erstellen können.

const identifyHandler = (request: IntentFlow.IdentifyRequest):
  IntentFlow.IdentifyResponse => {

    // Obtain scan data from protocol defined in your scan config
    const device = request.inputs[0].payload.device;
    if (device.udpScanData === undefined) {
      throw Error("Missing discovery response");
    }
    const scanData = device.udpScanData.data;

    // Decode scan data to obtain metadata about local device
    const verificationId = "local-device-id";

    // Return a response
    const response: IntentFlow.IdentifyResponse = {
      intent: Intents.IDENTIFY,
      requestId: request.requestId,
      payload: {
        device: {
          id: device.id || "",
          verificationId, // Must match otherDeviceIds in SYNC response
        },
      },
    };
    return response;
  };

const identifyHandler = (request: IntentFlow.IdentifyRequest):
  IntentFlow.IdentifyResponse => {

    // Obtain scan data from protocol defined in your scan config
    const device = request.inputs[0].payload.device;
    if (device.udpScanData === undefined) {
      throw Error("Missing discovery response");
    }
    const scanData = device.udpScanData.data;

    // Decode scan data to obtain metadata about local device
    const proxyDeviceId = "local-hub-id";

    // Return a response
    const response: IntentFlow.IdentifyResponse = {
      intent: Intents.IDENTIFY,
      requestId: request.requestId,
      payload: {
        device: {
          id: proxyDeviceId,
          isProxy: true,     // Device can control other local devices
          isLocalOnly: true, // Device not present in `SYNC` response
        },
      },
    };
    return response;
  };

Geräte hinter einem Hub identifizieren

Wenn Google ein Hub-Gerät erkennt, behandelt es den Hub als Kabel zu den verbundenen Hub-Geräten und versucht, diese Endgeräte zu überprüfen.

Folgen Sie der Anleitung für Ihren IDENTIFYHandler, damit Google prüfen kann, ob ein Hub-Gerät vorhanden ist:

• Wenn die Antwort SYNC die IDs lokaler Geräte enthält, die mit dem Hub verbunden sind, legen Sie isProxy im IdentifyResponsePayload auf true fest.
• Wenn Ihre SYNC-Antwort Ihr Hub-Gerät nicht meldet, legen Sie isLocalOnly im IdentifyResponsePayload als true fest.
• Das Feld device.id enthält die lokale Geräte-ID für das Hub-Gerät.

REACHABLE_DEVICES-Handler implementieren (nur Hub-Integrationen)

Der Intent REACHABLE_DEVICES wird von Google gesendet, um zu prüfen, welche Endgeräte lokal gesteuert werden können. Dieser Intent wird jedes Mal ausgelöst, wenn Google einen Discovery-Scan ausführt (etwa einmal pro Minute), solange erkannt wird, dass der Hub online ist.

Sie implementieren den REACHABLE_DEVICES-Handler ähnlich wie den IDENTIFY-Handler, mit dem Unterschied, dass Ihr Handler zusätzliche Geräte-IDs erfassen muss, die vom lokalen Proxy, also dem Hub-Gerät, erreichbar sind. Das Feld device.verificationId enthält die lokale Geräte-ID für ein Endgerät, das mit dem Hub verbunden ist.

Die ReachableDevicesRequest von der Local Home-Plattform enthält eine Instanz von LocalIdentifiedDevice. Über diese Instanz können Sie die Proxy-Geräte-ID sowie Daten aus den Scanergebnissen abrufen.

Der REACHABLE_DEVICES-Handler sollte ein ReachableDevicesPayload-Objekt zurückgeben, das ein devices-Objekt enthält, das ein Array von verificationId-Werten enthält, die die vom Hub gesteuerten Endgeräte darstellen. Die verificationId-Werte müssen mit einem der otherDeviceIds aus der SYNC-Antwort übereinstimmen.

Das folgende Snippet zeigt, wie Sie Ihren REACHABLE_DEVICES-Handler erstellen können.

const reachableDevicesHandler = (request: IntentFlow.ReachableDevicesRequest):
  IntentFlow.ReachableDevicesResponse => {

    // Reference to the local proxy device
    const proxyDeviceId = request.inputs[0].payload.device.id;

    // Gather additional device ids reachable by local proxy device
    // ...

    const reachableDevices = [
      // Each verificationId must match one of the otherDeviceIds
      // in the SYNC response
      { verificationId: "local-device-id-1" },
      { verificationId: "local-device-id-2" },
    ];

    // Return a response
    const response: IntentFlow.ReachableDevicesResponse = {
      intent: Intents.REACHABLE_DEVICES,
      requestId: request.requestId,
      payload: {
        devices: reachableDevices,
      },
    };
    return response;
  };

EXECUTE-Handler implementieren

Der EXECUTE-Handler in der App verarbeitet Nutzerbefehle und verwendet das Local Home SDK, um über ein vorhandenes Protokoll auf Ihre Smart-Home-Geräte zuzugreifen.

Die lokale Startseite weist dieselbe Nutzlast für die Eingabe an den Handler EXECUTE wie für den Intent EXECUTE an die Auftragsausführung in der Cloud zu. Außerdem gibt der EXECUTE-Handler Ausgabedaten im selben Format zurück wie beim Verarbeiten des EXECUTE-Intents. Mit der Execute.Response.Builder-Klasse, die vom Local Home SDK zur Verfügung gestellt wird, lässt sich die Antwort einfacher erstellen.

Ihre App hat keinen direkten Zugriff auf die IP-Adresse des Geräts. Verwenden Sie stattdessen die Schnittstelle CommandRequest, um Befehle auf der Grundlage eines dieser Protokolle zu erstellen: UDP, TCP oder HTTP. Rufen Sie dann die Funktion deviceManager.send() auf, um die Befehle zu senden.

Wenn Sie Geräte auf Befehle ausrichten, verwenden Sie die Geräte-ID (und die Parameter im Feld customData, falls eingeschlossen) aus der SYNC-Antwort, um mit dem Gerät zu kommunizieren.

Beispiel

Das folgende Code-Snippet zeigt, wie Sie den EXECUTE-Handler erstellen können.

const executeHandler = (request: IntentFlow.ExecuteRequest):
  Promise<IntentFlow.ExecuteResponse> => {

    // Extract command(s) and device target(s) from request
    const command = request.inputs[0].payload.commands[0];
    const execution = command.execution[0];

    const response = new Execute.Response.Builder()
      .setRequestId(request.requestId);

    const result = command.devices.map((device) => {
      // Target id of the device provided in the SYNC response
      const deviceId = device.id;
      // Metadata for the device provided in the SYNC response
      // Use customData to provide additional required execution parameters
      const customData: any = device.customData;

      // Convert execution command into payload for local device
      let devicePayload: string;
      // ...

      // Construct a local device command over TCP
      const deviceCommand = new DataFlow.TcpRequestData();
      deviceCommand.requestId = request.requestId;
      deviceCommand.deviceId = deviceId;
      deviceCommand.data = devicePayload;
      deviceCommand.port = customData.port;
      deviceCommand.operation = Constants.TcpOperation.WRITE;

      // Send command to the local device
      return localHomeApp.getDeviceManager()
        .send(deviceCommand)
        .then((result) => {
          response.setSuccessState(result.deviceId, state);
        })
        .catch((err: IntentFlow.HandlerError) => {
          err.errorCode = err.errorCode || IntentFlow.ErrorCode.INVALID_REQUEST;
          response.setErrorState(device.id, err.errorCode);
        });
    });

    // Respond once all commands complete
    return Promise.all(result)
      .then(() => response.build());
  };

QUERY-Handler implementieren

Der QUERY-Handler in der App verarbeitet Nutzeranfragen und verwendet den Local Home SDK, um den Status deiner Smart-Home-Geräte zu melden.

Die lokale Startseite übergibt die gleiche Nutzlast der Anfrage an die Handler-Funktion „QUERY“ wie den Intent QUERY an Ihre Cloud-Auftragsausführung. Außerdem gibt der QUERY-Handler Daten im selben Format zurück wie bei der Verarbeitung des QUERY-Intents.

Befehle an Geräte hinter einem Hub senden

Damit Sie Endgeräte hinter einem Hub steuern können, müssen Sie möglicherweise zusätzliche Informationen in der protokollspezifischen Befehlsnutzlast angeben, die an den Hub gesendet werden, damit der Hub erkennen kann, für welches Gerät der Befehl bestimmt ist. In einigen Fällen kann dies direkt aus dem Wert von device.id abgeleitet werden. In diesem Fall sollten Sie diese zusätzlichen Daten aber in das Feld customData aufnehmen.

Wenn Sie Ihre App mit TypeScript erstellt haben, müssen Sie sie in JavaScript kompilieren. Sie können den Code Ihres gewünschten Modulsystems verwenden. Das Ziel muss vom Chrome-Browser unterstützt werden.