Mengimplementasikan aplikasi fulfillment lokal

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

• IDENTIFY: Mendukung penemuan perangkat smart yang dapat dikontrol secara lokal. Pengendali intent mengekstrak data yang ditampilkan 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 belakang perangkat hub (atau bridge).

Aplikasi ini berjalan di perangkat Google Home atau Google Nest pengguna dan menghubungkan perangkat smart 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 detail selengkapnya tentang API, lihat Referensi API Local Home SDK.

Cuplikan berikut menunjukkan cara menginisialisasi aplikasi fulfillment lokal dan menambahkan 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");
  });

Buat project Anda

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

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

Template project

Untuk memilih konfigurasi bundler, jalankan perintah npm init seperti yang ditunjukkan dalam 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 umum tingkat proyek

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

Mengimplementasikan 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 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 akan menampilkan objek IdentifyResponsePayload, yang menyertakan objek device dengan metadata smart home (seperti jenis, karakteristik, 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 hub dan perangkat 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 Google mengidentifikasi perangkat hub, Google akan memperlakukan hub sebagai saluran ke perangkat akhir yang terhubung dari hub dan mencoba memverifikasi perangkat akhir tersebut.

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

• Jika respons SYNC Anda 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_PERANGKAT (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 (sekitar sekali setiap menit), selama hub terdeteksi sedang online.

Anda menerapkan pengendali REACHABLE_DEVICES yang mirip dengan pengendali IDENTIFY, kecuali pengendali Anda 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 Local Home 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 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;
  };

Mengimplementasikan pengendali EXECUTE

Pengendali EXECUTE di aplikasi memproses perintah pengguna dan menggunakan Local Home SDK untuk mengakses perangkat smart 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 akan menampilkan data output dalam format yang sama seperti dari pemrosesan 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 berikut: UDP, TCP, atau HTTP. Selanjutnya, 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());
  };

Mengimplementasikan pengendali QUERY

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

Platform Local Home meneruskan payload permintaan yang sama ke fungsi pengendali 'QUERY', seperti halnya intent QUERY ke fulfillment cloud Anda. Demikian pula, pengendali QUERY akan menampilkan data dalam format yang sama seperti dari pemrosesan intent QUERY.

Mengirimkan perintah ke perangkat di belakang hub

Untuk mengontrol perangkat akhir di belakang hub, Anda mungkin perlu memberikan informasi tambahan dalam payload perintah khusus protokol yang dikirim ke hub agar hub dapat mengidentifikasi perangkat yang menjadi tujuan perintah. Dalam beberapa kasus, hal ini dapat disimpulkan langsung 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.