Menerapkan aplikasi fulfillment lokal

Untuk mendukung fulfillment lokal, Anda perlu membuat aplikasi untuk menangani intent smart home ini:

• IDENTIFY: Mendukung penemuan perangkat smart yang dapat dikontrol secara lokal. Pengendali intent mengekstrak data yang ditampilkan oleh perangkat smart selama penemuan dan mengirimkannya sebagai respons ke Google.
• EXECUTE: Mendukung eksekusi perintah.
• QUERY: Mendukung pembuatan kueri status perangkat.
• REACHABLE_DEVICES: (Opsional) Mendukung penemuan perangkat akhir yang dapat dikontrol secara lokal di balik perangkat hub (atau jembatan).

Aplikasi ini berjalan di perangkat Google Home atau Google Nest milik pengguna dan menghubungkan perangkat smart Anda ke Asisten. Anda dapat membuat aplikasi menggunakan TypeScript (lebih disukai) atau JavaScript.

TypeScript direkomendasikan karena Anda dapat memanfaatkan binding untuk secara statis memastikan bahwa data yang ditampilkan aplikasi Anda sesuai dengan jenis yang diharapkan platform.

Untuk mengetahui detail API selengkapnya, lihat Referensi Local Home SDK API.

Cuplikan berikut menunjukkan cara menginisialisasi aplikasi fulfillment lokal dan menyertakan pengendali.

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

Membuat project

Untuk men-deploy aplikasi fulfillment lokal, Anda perlu mem-build paket JavaScript untuk kode Anda dan semua dependensinya.

Gunakan fulfillmenter project aplikasi fulfillment lokal untuk mem-bootstrap struktur project yang sesuai dengan konfigurasi bundler pilihan Anda.

Template project

Untuk memilih konfigurasi pemaket Anda, jalankan perintah npm init seperti yang ditunjukkan pada contoh berikut:

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

Melakukan tugas tingkat project umum

Project yang dihasilkan mendukung skrip npm berikut:

cd project-directory/
npm run build

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

cd project-directory/
npm run start

Menerapkan pengendali IDENTIFY

Pengendali IDENTIFY akan dipicu saat perangkat Google Home atau Google Nest dimulai ulang dan melihat perangkat lokal yang belum diverifikasi (termasuk perangkat akhir yang terhubung ke hub). Platform Local Home akan memindai perangkat lokal menggunakan informasi konfigurasi pemindaian yang Anda tentukan sebelumnya dan memanggil pengendali IDENTIFY Anda dengan hasil pemindaian.

IdentifyRequest dari platform Beranda Lokal berisi data pemindaian instance LocalIdentifiedDevice. Hanya satu instance device yang diisi, berdasarkan konfigurasi pemindaian yang menemukan perangkat.

Jika hasil pemindaian cocok dengan perangkat Anda, pengendali IDENTIFY Anda akan menampilkan objek IdentifyResponsePayload, yang menyertakan objek device dengan metadata smart home (seperti jenis, fitur, dan status laporan).

Google membuat atribusi perangkat jika verificationId dari respons IDENTIFY cocok dengan salah satu nilai otherDeviceIds yang ditampilkan oleh respons SYNC.

Contoh

Cuplikan berikut menunjukkan cara membuat pengendali IDENTIFY untuk integrasi perangkat dan hub mandiri.

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

Mengidentifikasi perangkat di balik hub

Jika mengidentifikasi perangkat hub, Google akan memperlakukan hub sebagai saluran ke perangkat akhir hub yang terhubung dan mencoba memverifikasi perangkat akhir tersebut.

Agar Google dapat mengonfirmasi bahwa perangkat hub ada, ikuti petunjuk berikut untuk pengendali IDENTIFY:

• Jika respons SYNC melaporkan ID perangkat akhir lokal yang terhubung ke hub, tetapkan isProxy sebagai true di IdentifyResponsePayload.
• Jika respons SYNC Anda tidak melaporkan perangkat hub, tetapkan isLocalOnly sebagai true di IdentifyResponsePayload.
• Kolom device.id berisi ID perangkat lokal untuk perangkat hub itu sendiri.

Terapkan pengendali REACHABLE_DEVICES (khusus integrasi hub)

Intent REACHABLE_DEVICES dikirim oleh Google untuk mengonfirmasi perangkat akhir mana yang dapat dikontrol secara lokal. Intent ini dipicu setiap kali Google menjalankan pemindaian penemuan (kira-kira sekali setiap menit), selama hub terdeteksi saat online.

Anda menerapkan pengendali REACHABLE_DEVICES mirip dengan pengendali IDENTIFY, tetapi pengendali harus mengumpulkan ID perangkat tambahan yang dapat dijangkau oleh perangkat proxy lokal (yaitu hub). Kolom device.verificationId berisi ID perangkat lokal untuk perangkat akhir yang terhubung ke hub.

ReachableDevicesRequest dari platform Home Lokal berisi instance LocalIdentifiedDevice. Melalui instance ini, Anda bisa mendapatkan ID perangkat proxy serta data dari hasil pemindaian.

Pengendali REACHABLE_DEVICES Anda harus menampilkan objek ReachableDevicesPayload yang menyertakan objek devices yang berisi array nilai verificationId yang mewakili perangkat akhir yang dikontrol oleh hub. Nilai verificationId harus cocok dengan salah satu otherDeviceIds dari respons SYNC.

Cuplikan berikut menunjukkan cara membuat pengendali REACHABLE_DEVICES.

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

Menerapkan pengendali EXECUTE

Pengendali EXECUTE Anda di aplikasi memproses perintah pengguna dan menggunakan Local Home SDK untuk mengakses perangkat smart Anda melalui protokol yang ada.

Platform Local Home meneruskan payload input yang sama ke fungsi pengendali EXECUTE seperti untuk intent EXECUTE ke fulfillment cloud Anda. Demikian pula, pengendali EXECUTE Anda menampilkan data output dalam format yang sama seperti dari memproses intent EXECUTE. Untuk menyederhanakan pembuatan respons, Anda dapat menggunakan class Execute.Response.Builder yang disediakan Local Home SDK.

Aplikasi Anda tidak memiliki akses langsung ke alamat IP perangkat. Sebagai gantinya, gunakan antarmuka CommandRequest untuk membuat perintah berdasarkan salah satu protokol ini: UDP, TCP, atau HTTP. Kemudian, panggil fungsi deviceManager.send() untuk mengirim perintah.

Saat menargetkan perintah ke perangkat, gunakan ID perangkat (dan parameter dari kolom customData, jika disertakan) dari respons SYNC untuk berkomunikasi dengan perangkat.

Contoh

Cuplikan kode berikut menunjukkan cara membuat pengendali EXECUTE.

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

Menerapkan pengendali QUERY

Pengendali QUERY Anda di aplikasi memproses permintaan pengguna dan menggunakan Local Home SDK untuk melaporkan status perangkat smart Anda.

Platform Local Home meneruskan payload permintaan yang sama ke fungsi pengendali 'QUERY' seperti untuk intent QUERY ke fulfillment cloud Anda. Demikian pula, pengendali QUERY Anda menampilkan data dalam format yang sama dengan memproses intent QUERY.

Mengirimkan perintah ke perangkat di belakang hub

Untuk mengontrol perangkat akhir di balik hub, Anda mungkin perlu memberikan informasi tambahan dalam payload perintah khusus protokol yang dikirim ke hub agar hub mengidentifikasi perangkat mana yang menjadi tujuan perintah. Dalam beberapa kasus, nilai ini dapat langsung disimpulkan dari nilai device.id, tetapi jika tidak, Anda harus menyertakan data tambahan ini sebagai bagian dari kolom customData.

Jika Anda membuat aplikasi menggunakan TypeScript, jangan lupa untuk mengompilasi aplikasi Anda ke JavaScript. Anda dapat menggunakan sistem modul pilihan Anda untuk menulis kode. Pastikan target Anda didukung oleh browser Chrome.