Menghubungkan perangkat smart home ke Asisten Google

Sebagai developer Internet of Things (IoT), Anda dapat membuat Action smart home yang memberi pengguna kemampuan untuk mengontrol perangkatnya melalui kontrol sentuh di aplikasi Google Home dan perintah suara dengan Asisten.

Action smart home mengandalkan Home Graph untuk memberikan data kontekstual tentang rumah dan perangkatnya, membuat peta logis rumah. Konteks tersebut memberikan Asisten pemahaman yang lebih alami tentang permintaan pengguna terkait lokasinya di rumah. Misalnya, Home Graph dapat menyimpan konsep ruang keluarga yang berisi berbagai jenis perangkat dari produsen yang berbeda, seperti termostat, lampu, kipas angin, dan penyedot debu.

Prasyarat

• Panduan developer Membuat Action smart home

Yang akan Anda buat

Dalam codelab ini, Anda akan memublikasikan layanan cloud yang mengelola mesin cuci smart virtual, kemudian membuat Action smart home dan menghubungkannya ke Asisten.

Yang akan Anda pelajari

• Cara men-deploy layanan cloud smart home
• Cara menghubungkan layanan ke Asisten
• Cara memublikasikan perubahan status perangkat ke Google

Yang Anda butuhkan

• Browser web, seperti Google Chrome
• Perangkat iOS atau Android yang telah menginstal aplikasi Google Home
• Node.js versi 10.16 atau yang lebih baru
• Akun penagihan Google Cloud.

Mengaktifkan Kontrol aktivitas

Aktifkan Kontrol aktivitas berikut di Akun Google yang akan Anda gunakan dengan Asisten:

• Aktivitas Web & Aplikasi
• Informasi Perangkat
• Aktivitas Suara & Audio

Anda akan memerlukan Akun Google yang sama di ponsel Anda dengan di Konsol Actions untuk menjalankan project ini sepenuhnya.

Membuat project Actions

1. Buka Actions di Google Developers Console.
2. Klik New Project, masukkan nama untuk project, dan klik CREATE PROJECT.

Memilih Aplikasi Smart Home

Pada layar Overview di Konsol Actions, pilih Smart home.

Pilih kartu pengalaman Smart home, lalu Anda akan diarahkan ke konsol project.

Project ini menggunakan Cloud Functions for Firebase, yang mengharuskan Anda mengaitkan sebuah akun penagihan ke project Anda. Project Action tidak membuat akun penagihan secara default. Lihat Membuat akun penagihan baru untuk informasi selengkapnya.

Menginstal Firebase CLI

Antarmuka Command Line (CLI) Firebase akan memungkinkan Anda menyalurkan aplikasi web secara lokal dan men-deploy aplikasi web ke Firebase hosting.

Untuk menginstal CLI, Anda harus menginstal npm yang biasanya disertai dengan Node.js.

Untuk menginstal CLI, jalankan perintah npm berikut dari terminal:

npm install -g firebase-tools

Tidak berhasil? Mungkin Anda perlu mengubah izin npm.

Untuk memverifikasi bahwa CLI telah diinstal dengan benar, jalankan:

firebase --version

Otorisasikan Firebase CLI dengan Akun Google Anda dengan menjalankan:

firebase login

Kini, setelah lingkungan pengembangan sudah disiapkan, Anda dapat men-deploy project pemicu untuk memverifikasi bahwa semuanya telah dikonfigurasi dengan benar.

Mendapatkan kode sumber

Klik link berikut untuk mendownload contoh codelab ini di mesin pengembangan Anda:

Download kode sumber

...atau Anda dapat meng-clone repositori GitHub dari command line:

git clone https://github.com/googlecodelabs/smarthome-washer.git

Catatan: Repositori codelab berisi dua direktori:

• washer-start—Kode awal yang menjadi dasar pembuatan.
• washer-done—Kode lengkap untuk aplikasi contoh mesin cuci yang sudah selesai.

Jika Anda ingin menjalankan aplikasi yang sudah selesai, Anda masih perlu membuat project di Konsol Actions.

Tentang project

Project pemicu berisi subdirektori berikut:

• public: UI frontend untuk mengontrol dan memantau status mesin cuci smart dengan mudah.
• functions: Layanan cloud yang diterapkan sepenuhnya untuk mengelola mesin cuci smart dengan Cloud Functions for Firebase dan Firebase Realtime Database.

Tips: Cari penanda TODO.

Project pemicu memberikan petunjuk tentang tempat Anda harus mengubah atau menambahkan kode. Contoh:

// TODO: Implement full SYNC response

Menghubungkan ke Firebase

Buka direktori washer-start, lalu siapkan Firebase CLI dengan project Actions Anda:

cd washer-start
firebase use <project-id>

Tips: Jika tidak mengetahui project ID untuk Action smart home, Anda dapat menemukannya di Konsol Actions di bagian Setelan project.

Men-deploy ke Firebase

Buka folder functions dan instal semua dependensi yang dibutuhkan menggunakan npm.

cd functions
npm install

Kini, setelah menginstal dependensi dan mengonfigurasi project, Anda siap menjalankan aplikasi untuk pertama kali.

firebase deploy

Ini adalah output konsol yang akan Anda lihat:

...

✔ Deploy complete!

Project Console: https://console.firebase.google.com/project/<project-id>/overview
Hosting URL: https://<project-id>.firebaseapp.com

Perintah ini men-deploy aplikasi web, bersama dengan beberapa Cloud Functions for Firebase.

Buka URL Hosting di browser Anda (https://<project-id>.firebaseapp.com) untuk melihat aplikasi web. Anda akan melihat antarmuka berikut:

UI web ini mewakili platform pihak ketiga untuk melihat atau mengubah status perangkat. Untuk mulai mengisi database Anda dengan informasi perangkat, klik UPDATE. Anda tidak akan melihat perubahan apa pun di halaman ini, tapi status mesin cuci saat ini akan disimpan dalam database.

Catatan: Status perangkat virtual disimpan menggunakan Firebase Realtime Database. Anda dapat melihat isi database secara langsung menggunakan Firebase console. Di toolbar sebelah kiri, klik Develop > Database. Setiap pembaruan status mesin cuci akan tercermin di sini.

Sekarang saatnya menghubungkan layanan cloud yang telah Anda deploy ke Asisten Google menggunakan Konsol Actions.

Mengonfigurasi project Konsol Action Anda

Di bagian Overview > Build your Action, pilih Add Action(s). Masukkan URL untuk Cloud Function Anda yang menyediakan fulfillment untuk intent smart home, lalu klik Save.

https://us-central1-<project-id>.cloudfunctions.net/smarthome

Di tab Develop > Invocation, tambahkan Display Name untuk Action Anda, lalu klik Save. Nama ini akan muncul di aplikasi Google Home.

Untuk mengaktifkan penautan Akun, pilih opsi Develop > Account linking di navigasi sebelah kiri. Gunakan setelan penautan akun berikut:

Client ID	ABC123
Rahasia klien	DEF456
URL otorisasi	https://us-central1-<project-id>.cloudfunctions.net/fakeauth
URL Token	https://us-central1-<project-id>.cloudfunctions.net/faketoken

Pastikan untuk memperbarui URL dengan project ID Anda.

Klik Save untuk menyimpan konfigurasi penautan akun Anda, lalu klik Test untuk mengaktifkan pengujian project Anda.

Anda akan dialihkan ke Simulator. Verifikasikan bahwa pengujian telah diaktifkan untuk project Anda dengan mengarahkan mouse ke ikon Testing on Device ( ).

Sekarang Anda dapat mulai mengimplementasikan webhook yang diperlukan untuk menghubungkan status perangkat dengan Asisten.

Kini, setelah mengonfigurasi Action, Anda dapat menambahkan perangkat dan mengirimkan data. Layanan cloud Anda perlu menangani intent berikut:

• Intent SYNC terjadi saat Asisten ingin mengetahui perangkat apa saja yang telah dihubungkan oleh pengguna. Ini akan dikirim ke layanan saat pengguna menautkan akun. Anda harus menanggapi dengan payload JSON dari semua perangkat pengguna dan kemampuannya.
• Intent QUERY terjadi saat Asisten ingin mengetahui situasi atau status perangkat saat ini. Anda harus menanggapi dengan payload JSON dengan status setiap perangkat yang diminta.
• Intent EXECUTE terjadi saat Asisten ingin mengontrol perangkat atas nama pengguna. Anda harus menanggapi dengan payload JSON dengan status eksekusi setiap perangkat yang diminta.
• Intent DISCONNECT terjadi saat pengguna membatalkan tautan akunnya dari Asisten. Anda harus berhenti mengirim peristiwa untuk perangkat pengguna ini ke Asisten.

Anda akan memperbarui fungsi yang sebelumnya di-deploy untuk menangani intent ini di bagian berikut.

Memperbarui respons SYNC

Buka functions/index.js, yang berisi kode untuk merespons permintaan dari Asisten.

Anda perlu menangani SYNC intent dengan mengembalikan metadata dan kemampuan perangkat. Perbarui JSON di onSync array untuk menyertakan informasi perangkat dan fitur yang direkomendasikan untuk mesin cuci pakaian.

index.js

app.onSync((body) => {
  return {
    requestId: body.requestId,
    payload: {
      agentUserId: USER_ID,
      devices: [{
        id: 'washer',
        type: 'action.devices.types.WASHER',
        traits: [
          'action.devices.traits.OnOff',
          'action.devices.traits.StartStop',
          'action.devices.traits.RunCycle',
        ],
        name: {
          defaultNames: ['My Washer'],
          name: 'Washer',
          nicknames: ['Washer'],
        },
        deviceInfo: {
          manufacturer: 'Acme Co',
          model: 'acme-washer',
          hwVersion: '1.0',
          swVersion: '1.0.1',
        },
        willReportState: true,
        attributes: {
          pausable: true,
        },
      }],
    },
  };
});

Men-deploy ke Firebase

Deploy fulfillment cloud yang telah diupdate menggunakan Firebase CLI:

firebase deploy --only functions

Menautkan ke Asisten Google

Untuk menguji Action smart home, Anda harus menautkan project dengan Akun Google. Hal ini memungkinkan pengujian melalui platform Asisten Google dan aplikasi Google Home yang login ke akun yang sama.

Penting: Codelab ini mencakup penerapan penautan akun yang sebenarnya tidak memeriksa kredensial pengguna. Dalam sebuah sistem produksi, Anda harus menerapkan protokol OAuth 2.0 untuk menjaga keamanan perangkat.

1. Di ponsel, buka aplikasi Asisten Google. Perhatikan bahwa Anda harus login sebagai akun yang sama seperti di konsol.
2. Buka Google Assistant > Settings > Home Control (di bagian Asisten).
3. Klik ikon (+) di sudut kanan bawah
4. Anda akan melihat aplikasi pengujian dengan awalan [test] dan nama tampilan yang Anda tetapkan.
5. Pilih item tersebut. Kemudian, Asisten Google akan mengautentikasi dengan layanan Anda dan mengirimkan permintaan SYNC, meminta layanan Anda untuk memberikan daftar perangkat bagi pengguna.

Buka aplikasi Google Home dan verifikasikan bahwa Anda dapat melihat perangkat mesin cucinya.

Catatan: Jika mengalami masalah selama langkah penautan ini, Anda dapat memeriksa log error menggunakan Stackdriver.

Kini, setelah layanan cloud Anda melaporkan perangkat perangkatnya ke Google dengan benar, Anda perlu menambahkan kemampuan untuk meminta status perangkat dan mengirim perintah.

Menangani intent QUERY

Intent QUERY mencakup serangkaian perangkat. Untuk setiap perangkat, Anda harus merespons dengan statusnya saat ini.

Di functions/index.js, edit pengendali QUERY untuk memproses daftar perangkat target yang terdapat dalam permintaan intent.

index.js

app.onQuery(async (body) => {
  const {requestId} = body;
  const payload = {
    devices: {},
  };
  const queryPromises = [];
  const intent = body.inputs[0];
  for (const device of intent.payload.devices) {
    const deviceId = device.id;
    queryPromises.push(queryDevice(deviceId)
        .then((data) => {
        // Add response to device payload
          payload.devices[deviceId] = data;
        }
        ));
  }
  // Wait for all promises to resolve
  await Promise.all(queryPromises);
  return {
    requestId: requestId,
    payload: payload,
  };
});

Untuk setiap perangkat yang tercakup dalam permintaan, tampilkan status saat ini yang tersimpan di Realtime Database. Update fungsi queryFirebase dan queryDevice untuk menampilkan data status mesin cuci.

index.js

const queryFirebase = async (deviceId) => {
  const snapshot = await firebaseRef.child(deviceId).once('value');
  const snapshotVal = snapshot.val();
  return {
    on: snapshotVal.OnOff.on,
    isPaused: snapshotVal.StartStop.isPaused,
    isRunning: snapshotVal.StartStop.isRunning,
  };
};

const queryDevice = async (deviceId) => {
  const data = await queryFirebase(deviceId);
  return {
    on: data.on,
    isPaused: data.isPaused,
    isRunning: data.isRunning,
    currentRunCycle: [{
      currentCycle: 'rinse',
      nextCycle: 'spin',
      lang: 'en',
    }],
    currentTotalRemainingTime: 1212,
    currentCycleRemainingTime: 301,
  };
};

Menangani intent EXECUTE

Intent EXECUTE menangani perintah untuk mengupdate status perangkat. Respons akan menampilkan status setiap perintah—misalnya, SUCCESS, ERROR, atau PENDING—dan status perangkat baru.

Di functions/index.js, edit pengendali EXECUTE untuk memproses daftar karakteristik yang memerlukan update dan rangkaian perangkat target untuk setiap perintah:

index.js

app.onExecute(async (body) => {
  const {requestId} = body;
  // Execution results are grouped by status
  const result = {
    ids: [],
    status: 'SUCCESS',
    states: {
      online: true,
    },
  };

  const executePromises = [];
  const intent = body.inputs[0];
  for (const command of intent.payload.commands) {
    for (const device of command.devices) {
      for (const execution of command.execution) {
        executePromises.push(
            updateDevice(execution, device.id)
                .then((data) => {
                  result.ids.push(device.id);
                  Object.assign(result.states, data);
                })
                .catch(() => functions.logger.error('EXECUTE', device.id)));
      }
    }
  }

  await Promise.all(executePromises);
  return {
    requestId: requestId,
    payload: {
      commands: [result],
    },
  };
});

Untuk setiap perintah dan perangkat target, perbarui nilai di Realtime Database yang sesuai dengan karakteristik yang diminta. Ubah fungsi updateDevice untuk memperbarui referensi Firebase yang sesuai dan menampilkan status perangkat yang diperbarui.

index.js

const updateDevice = async (execution, deviceId) => {
  const {params, command} = execution;
  let state; let ref;
  switch (command) {
    case 'action.devices.commands.OnOff':
      state = {on: params.on};
      ref = firebaseRef.child(deviceId).child('OnOff');
      break;
    case 'action.devices.commands.StartStop':
      state = {isRunning: params.start};
      ref = firebaseRef.child(deviceId).child('StartStop');
      break;
    case 'action.devices.commands.PauseUnpause':
      state = {isPaused: params.pause};
      ref = firebaseRef.child(deviceId).child('StartStop');
      break;
  }

  return ref.update(state)
      .then(() => state);
};

Catatan: Tidak ada kode dalam pengendali EXECUTE untuk karakteristik RunCycle karena merupakan karakteristik hanya baca yang tidak mendukung perintah.

Setelah menerapkan ketiga intent, Anda dapat menguji bahwa Action Anda mengontrol mesin cuci.

Men-deploy ke Firebase

Deploy fulfillment cloud yang telah diupdate menggunakan Firebase CLI:

firebase deploy --only functions

Menguji mesin cuci

Sekarang Anda dapat melihat perubahan nilai saat mencoba salah satu perintah suara berikut melalui ponsel:

"Ok Google, nyalakan mesin cuci".

"Ok Google, jeda mesin cuci saya".

"Ok Google, hentikan mesin cuci saya".

Anda juga dapat melihat status mesin cuci saat ini dengan mengajukan pertanyaan.

"Ok Google, apa mesin cuci saya menyala?"

"Ok Google, apa mesin cuci saya sedang bekerja?"

"Ok Google, mesin cuci saya sedang berada di siklus apa?"

Anda juga dapat melihat kueri dan perintah ini di log Firebase console dengan mengklik Develop > Functions > Logs di menu navigasi.

Anda telah mengintegrasikan layanan cloud sepenuhnya dengan intent smart home, sehingga memungkinkan pengguna mengontrol dan mengajukan kueri mengenai status perangkat saat ini. Namun, implementasi tersebut belum memiliki cara untuk membuat layanan Anda mengirim informasi peristiwa secara proaktif ke Asisten, misalnya, perubahan kehadiran atau status perangkat.

Dengan Request Sync, Anda dapat memicu permintaan sinkronisasi baru saat pengguna menambahkan atau menghapus perangkat, atau saat kemampuan perangkat berubah. Dengan Report State, layanan cloud Anda dapat secara proaktif mengirimkan status perangkat ke Home Graph saat pengguna mengubah status perangkat secara fisik, misalnya, mengaktifkan sakelar lampu, atau mengubah status menggunakan layanan lain.

Di bagian ini, Anda akan menambahkan kode untuk memanggil metode ini dari aplikasi web frontend.

Catatan: Pastikan bahwa Action smart home Anda berhenti mengirimkan pembaruan ke Google setelah menerima intent DISCONNECT untuk pengguna tertentu. Intent ini menunjukkan bahwa pengguna telah membatalkan tautan akunnya dari Asisten.

Mengaktifkan HomeGraph API

HomeGraph API memungkinkan penyimpanan dan pembuatan kueri perangkat dan statusnya dalam Home Graph pengguna. Untuk menggunakan API ini, Anda harus membuka Google Cloud Console dan mengaktifkan HomeGraph API terlebih dulu.

Di Google Cloud Console, pastikan memilih project yang cocok dengan Action Anda <project-id>. Lalu, di layar API Library untuk HomeGraph API, klik Enable.

Mengaktifkan Report State

Tulis fungsi reportstate ke pemicu Realtime Database di project pemicu. Update fungsi reportstate di functions/index.js untuk mengambil data yang ditulis ke database dan mempostingnya ke Home Graph melalui Report State.

index.js

exports.reportstate = functions.database.ref('{deviceId}').onWrite(
    async (change, context) => {
      functions.logger.info('Firebase write event triggered Report State');
      const snapshot = change.after.val();

      const requestBody = {
        requestId: 'ff36a3cc', /* Any unique ID */
        agentUserId: USER_ID,
        payload: {
          devices: {
            states: {
              /* Report the current state of our washer */
              [context.params.deviceId]: {
                on: snapshot.OnOff.on,
                isPaused: snapshot.StartStop.isPaused,
                isRunning: snapshot.StartStop.isRunning,
              },
            },
          },
        },
      };

      const res = await homegraph.devices.reportStateAndNotification({
        requestBody,
      });
      functions.logger.info('Report state response:', res.status, res.data);
    });

Mengaktifkan Request Sync

Memuat ulang ikon di UI web frontend akan memicu fungsi requestsync di project pemicu. Implementasikan fungsi requestsync di functions/index.js untuk memanggil HomeGraph API.

index.js

exports.requestsync = functions.https.onRequest(async (request, response) => {
  response.set('Access-Control-Allow-Origin', '*');
  functions.logger.info(`Request SYNC for user ${USER_ID}`);
  try {
    const res = await homegraph.devices.requestSync({
      requestBody: {
        agentUserId: USER_ID,
      },
    });
    functions.logger.info('Request sync response:', res.status, res.data);
    response.json(res.data);
  } catch (err) {
    functions.logger.error(err);
    response.status(500).send(`Error requesting sync: ${err}`);
  }
});

Men-deploy ke Firebase

Deploy kode yang telah diperbarui menggunakan Firebase CLI:

firebase deploy --only functions

Menguji implementasi Anda

Klik tombol Refresh di UI web dan verifikasikan bahwa Anda melihat permintaan sinkronisasi di log Firebase console.

Selanjutnya, sesuaikan atribut perangkat mesin cuci di UI web frontend dan klik Update. Verifikasikan bahwa Anda dapat melihat perubahan status yang dilaporkan ke Google di log Firebase console Anda.

Selamat! Anda berhasil mengintegrasikan Asisten dengan layanan cloud perangkat menggunakan Action smart home.

Pelajari lebih lanjut

Berikut adalah beberapa ide yang dapat Anda lakukan untuk penerapan lebih dalam:

• Tambahkan mode dan pengalih ke perangkat Anda.
• Tambahkan karakteristik yang didukung lainnya ke perangkat Anda.
• Jelajahi eksekusi lokal untuk smart home.
• Lihat sampel GitHub kami untuk mempelajari lebih lanjut.

Anda juga dapat mempelajari lebih lanjut tentang menguji dan mengirimkan Action untuk ditinjau, termasuk proses sertifikasi untuk memublikasikan Action ke pengguna.