Men-debug Smart Home

1. Sebelum memulai

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

Mempelajari alat proses debug untuk integrasi Cloud-to-cloud adalah langkah penting untuk membangun integrasi berkualitas produksi dengan Google Assistant. Untuk memfasilitasi pemantauan dan proses debug yang mudah, Metrik Google Cloud Platform (GCP) serta Logging dan Test Suite untuk smart home tersedia untuk membantu Anda mengidentifikasi dan menyelesaikan masalah pada integrasi.

Prasyarat

• Baca panduan developer Membuat integrasi cloud-ke-cloud
• Jalankan codelab Menghubungkan perangkat smart home ke Asisten Google

Yang akan Anda build

Dalam codelab ini, Anda akan men-deploy integrasi Cloud-to-cloud dengan 2 kerusakan dan menghubungkannya ke Asisten, lalu men-debug kerusakan integrasi dengan Test Suite untuk metrik dan logging smart home & Google Cloud Platform (GCP).

Yang akan Anda pelajari

• Cara menggunakan Metrik dan Logging GCP untuk mengidentifikasi dan menyelesaikan masalah produksi
• Cara menggunakan Test Suite untuk smart home guna mengidentifikasi masalah fungsional dan API

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

2. Menjalankan aplikasi yang bermasalah

Mendapatkan kode sumber

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

file_downloadDownload kode sumber

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

$ git clone https://github.com/google-home/smarthome-debug.git

Tentang project ini

Aplikasi mesin cuci 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

Menghubungkan ke Firebase

Buka terminal di mesin pengembangan Anda. Buka direktori washer-faulty, lalu siapkan Firebase CLI dengan project integrasi Anda yang dibuat di Connect smart home devices to the Google Assistant codelab:

$ cd washer-faulty
$ firebase use <firebase-project-id>

Men-deploy ke Firebase

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

$ cd functions
$ npm install

Catatan: Jika Anda melihat pesan di bawah, Anda dapat mengabaikannya dan melanjutkan. Peringatan ini disebabkan oleh beberapa dependensi lama dan Anda dapat menemukan detail selengkapnya di sini.

found 5 high severity vulnerabilities
  run `npm audit fix` to fix them, or `npm audit` for details

Kini, setelah menginstal dependensi dan mengonfigurasi project, Anda siap men-deploy aplikasi mesin cuci yang rusak.

$ firebase deploy

Ini adalah output konsol yang akan Anda lihat:

...

✔ Deploy complete!

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

Memperbarui HomeGraph

Buka URL Hosting di browser Anda (https://<firebase-project-id>.firebaseapp.com) untuk melihat aplikasi web. Di UI web, klik tombol Segarkan untuk memperbarui HomeGraph dengan metadata perangkat terbaru dari aplikasi mesin cuci yang bermasalah menggunakan Sinkronisasi Permintaan.

Buka aplikasi Google Home dan verifikasikan bahwa Anda dapat melihat perangkat mesin cuci bernama Faulty Washer.

3. Menguji Integrasi Anda

Setelah men-deploy project, uji bahwa integrasi Anda mengontrol mesin cuci.

Menguji mesin cuci

Periksa perubahan nilai saat Anda mencoba salah satu perintah suara berikut melalui ponsel:

"Ok Google, nyalakan mesin cuci".

"Ok Google, mulai mesin cuci saya".

"Ok Google, jeda mesin cuci saya".

"Ok Google, lanjutkan mesin cuci saya".

"Ok Google, hentikan mesin cuci saya".

Anda akan melihat Asisten merespons bahwa ada yang salah dengan suara saat Anda menjeda / melanjutkan mesin cuci:

"Maaf, saya tidak dapat menghubungi <nama tampilan project>."

Untuk men-debug masalah ini, Anda harus mendapatkan informasi selengkapnya tentang error tersebut terlebih dahulu untuk mempersempit dan mengidentifikasi penyebab utamanya.

Dasbor Smarthome Analytics

Tempat yang tepat untuk memeriksa error adalah dasbor Analytics Smart Home, yang menggabungkan diagram metrik Penggunaan dan Kondisi untuk pemenuhan cloud Anda:

• Metrik Penggunaan mencerminkan tren penggunaan integrasi Cloud-to-cloud Anda, termasuk jumlah pengguna aktif harian dan jumlah total permintaan ke pemenuhan Anda.
• Metrik Kesehatan membantu Anda memantau terjadinya anomali pada integrasi Cloud-to-cloud, yang mencakup latensi permintaan, persentase keberhasilan, dan perincian error.

Untuk mempersempit penyebab error, ikuti langkah-langkah di bawah untuk mengakses dasbor project.

1. Di Developer Console, buka halaman Project.
2. Pilih project smart home Anda.
3. Klik tab Analytics di menu sebelah kiri.

4. Tindakan ini akan mengarahkan Anda ke daftar dasbor untuk project Anda di Google Cloud. Pilih dasbor Google Home Analytics - Cloud Integration.

5. Scroll ke bawah ke diagram Error Pemenuhan Cloud - Perincian Status untuk melihat kode error untuk rentang waktu yang ditandai.

Kode error PARTNER_RESPONSE_MISSING_DEVICE memberikan petunjuk tentang akar masalah. Selanjutnya, ambil log peristiwa berdasarkan kode error untuk mengetahui detail selengkapnya.

Mengakses log peristiwa

Untuk mendapatkan detail selengkapnya tentang error, akses log peristiwa untuk integrasi Cloud-to-Cloud Anda menggunakan Cloud Logging.

Buka Navigation Menu di Google Cloud Platform, lalu di bagian Operations, pilih Logging > Logs Explorer untuk mengakses log peristiwa project Anda. Atau, Anda dapat menelusuri Logs Explorer di kotak penelusuran.

Di kolom input Search all fields, masukkan kueri PARTNER_RESPONSE_MISSING_DEVICE, lalu klik Run Query. Log yang cocok dengan kueri akan ditampilkan di bagian Results.

Log error menampilkan peristiwa smart home dengan detail error yang menunjukkan:

• Tindakan pengguna yang dilakukan adalah "melanjutkan mesin cuci" (actionType: "STARTSTOP_UNPAUSE"), yang sesuai dengan perintah suara yang gagal baru-baru ini.
• Pesan debug terkait adalah "JSON response does not include device."

Berdasarkan pesan pen-debug-an, Anda harus memeriksa alasan aplikasi mesin cuci tidak menyertakan perangkat yang benar dalam respons EXECUTE.

Identifikasi penyebab utama error

Di functions/index.js, temukan pengendali EXECUTE (dalam array onExecute) yang menampilkan status setiap perintah dan status perangkat baru. Penyisipan ID perangkat ke dalam respons EXECUTE bergantung pada penyelesaian fungsi updateDevice:

index.js

app.onExecute(async (body) => {
 ...

 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((e) =>
                 functions.logger.error('EXECUTE',
                     device.id, e.message)));
     }
   }
 }

Periksa lebih lanjut cara fungsi updateDevice menangani jeda / lanjutkan di mesin cuci, dan Anda akan menemukan bahwa string yang cocok untuk perintah jeda / lanjutkan salah:

index.js

const updateDevice = async (execution, deviceId) => {
 const {params, command} = execution;
 let state; let ref;
 switch (command) {
   ...
   case 'action.devices.commands.PauseUnpausePause':
      const data = await queryDevice(deviceId);
      state = (data.isPaused === false && data.isRunning === false)
        ? {isRunning: false, isPaused: false}
        : {isRunning: !params.pause, isPaused: params.pause};
      ref = getFirebaseRef().child(deviceId).child('StartStop');
      break;
 }

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

Perbaiki error

Setelah mengidentifikasi penyebab utama error, Anda dapat memperbaiki string untuk perintah jeda / lanjutkan:

index.js

const updateDevice = async (execution, deviceId) => {
 const {params, command} = execution;
 let state; let ref;
 switch (command) {
   ...
   case 'action.devices.commands.PauseUnpause':
      const data = await queryDevice(deviceId);
      state = (data.isPaused === false && data.isRunning === false)
        ? {isRunning: false, isPaused: false}
        : {isRunning: !params.pause, isPaused: params.pause};
      ref = getFirebaseRef().child(deviceId).child('StartStop');
      break;
 }

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

Menguji perbaikan

Deploy kode yang telah diperbarui menggunakan Firebase CLI:

firebase deploy --only functions

Coba lagi perintah suara berikut, dan Anda akan melihat bahwa Asisten kini merespons dengan benar saat Anda menjeda / melanjutkan mesin cuci.

"Ok Google, jeda mesin cuci saya".

=>

"Oke, menjeda mesin cuci."

"Ok Google, lanjutkan mesin cuci saya".

=>

"Oke, melanjutkan mesin cuci".

Anda juga dapat menguji 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?"

4. Menguji integrasi Anda dengan Test Suite

Selain menguji secara manual, Anda dapat menggunakan Test Suite untuk smart home otomatis guna memvalidasi kasus penggunaan berdasarkan jenis dan karakteristik perangkat yang terkait dengan integrasi Anda. Test Suite menjalankan serangkaian pengujian untuk mendeteksi masalah dalam integrasi Anda, dan menampilkan pesan informatif untuk kasus pengujian yang gagal guna mempercepat proses penelusuran bug sebelum mempelajari log peristiwa.

Menjalankan Test Suite untuk smart home

Ikuti petunjuk berikut untuk menguji integrasi Cloud-to-cloud Anda berdasarkan Test Suite:

1. Di browser web Anda, buka Test Suite untuk smart home.
2. Login ke Google menggunakan tombol di pojok kanan atas. Hal ini memungkinkan Test Suite mengirim perintah langsung ke Asisten Google.
3. Di kolom Project ID, masukkan project ID integrasi Cloud-to-cloud Anda. Kemudian, klik BERIKUTNYA untuk melanjutkan.
4. Pada langkah Setelan Pengujian, Anda akan melihat Test Suite mencantumkan jenis dan karakteristik perangkat mesin cuci.

5. Nonaktifkan opsi Sinkronisasi Permintaan Pengujian karena aplikasi mesin cuci contoh tidak memiliki UI untuk menambahkan / menghapus / mengganti nama mesin cuci. Dalam sistem produksi, Anda harus memicu Request Sync setiap kali pengguna menambahkan / menghapus / mengganti nama perangkat.
6. Klik BERIKUTNYA untuk mulai menjalankan pengujian.

Setelah Test Suite selesai berjalan, lihat hasil kasus pengujian. Anda akan melihat dua kasus pengujian yang gagal dengan pesan error masing-masing:

Untuk men-debug integrasi Cloud-to-cloud yang gagal, Anda harus mengidentifikasi akar penyebab error dengan menganalisis pesan error terlebih dahulu.

Menganalisis pesan error

Untuk membantu developer mengidentifikasi penyebab utama, Test Suite menampilkan pesan error untuk setiap kasus pengujian yang gagal yang menunjukkan alasan kegagalan.

Untuk kasus pengujian pertama yang gagal di atas,

pesan errornya menunjukkan bahwa Test Suite mengharapkan "isPause": true dalam status yang dilaporkan dari integrasi Cloud-to-cloud Anda, tetapi status sebenarnya hanya mencakup "isPause": false.

Selain itu, pesan error kasus pengujian kedua yang gagal menunjukkan bahwa status dalam respons QUERY dari integrasi Cloud-ke-cloud Anda mencakup "isPause": true, yang berbeda dari "isPause": false dalam status yang dilaporkan dari integrasi Cloud-ke-cloud Anda:

Menurut kedua pesan error tersebut, Anda kemudian harus memeriksa apakah laporan integrasi Anda menyatakan isPaused dengan nilai yang benar.

Identifikasi penyebab utama error

Buka functions/index.js, yang berisi fungsi reportstate yang memposting perubahan status ke Home Graph menggunakan Report State. Periksa payload Status Laporan, dan Anda akan menemukan bahwa payload tidak memiliki status isPaused, yang persis seperti yang diperiksa oleh Test Suite dalam kasus pengujian yang gagal.

index.js

exports.reportstate = functions.database.ref('{deviceId}').onWrite(
    async (change, context) => {
      ...

      const requestBody = {
        requestId: 'ff36a3cc', /* Any unique ID */
        agentUserId: USER_ID,
        payload: {
          devices: {
            states: {
              /* Report the current state of our washer */
             [context.params.deviceId]: {
                online: snapshot.online,
                on: snapshot.OnOff.on,
                isRunning: snapshot.StartStop.isRunning,
                currentRunCycle: [{
                  currentCycle: 'rinse',
                  nextCycle: 'spin',
                  lang: 'en',
                }],
                currentTotalRemainingTime: 1212,
                currentCycleRemainingTime: 301,
              },
            },
          },
        },
      };

      const res = await homegraph.devices.reportStateAndNotification({
        requestBody,
      });
      ...
    });

Perbaiki error

Setelah mengidentifikasi akar penyebab error, revisi functions/index.js dengan menambahkan status isPaused ke payload Status Laporan:

index.js

exports.reportstate = functions.database.ref('{deviceId}').onWrite(
    async (change, context) => {
      ...

      const requestBody = {
        requestId: 'ff36a3cc', /* Any unique ID */
        agentUserId: USER_ID,
        payload: {
          devices: {
            states: {
              /* Report the current state of our washer */
             [context.params.deviceId]: {
                online: snapshot.online,
                on: snapshot.OnOff.on,
                isPaused: snapshot.StartStop.isPaused,
                isRunning: snapshot.StartStop.isRunning,
                currentRunCycle: [{
                  currentCycle: 'rinse',
                  nextCycle: 'spin',
                  lang: 'en',
                }],
                currentTotalRemainingTime: 1212,
                currentCycleRemainingTime: 301,
              },
            },
          },
        },
      };
      ...
    });

Menguji perbaikan

Deploy kode yang telah diperbarui menggunakan Firebase CLI:

$ firebase deploy --only functions

Jalankan kembali Rangkaian Pengujian untuk smart home, dan Anda akan melihat bahwa semua kasus pengujian telah berhasil.

5. Selamat

Selamat! Anda telah berhasil mempelajari cara memecahkan masalah integrasi Cloud-to-cloud menggunakan Test Suite untuk smart home & Metrik dan Logging GCP.

Pelajari lebih lanjut

Dari Codelab ini, coba latihan berikut dan jelajahi resource tambahan:

• Tambahkan karakteristik yang didukung lainnya ke perangkat Anda dan uji dengan Rangkaian Pengujian.
• Buat dasbor, siapkan pemberitahuan, dan akses data metrik secara terprogram untuk mendapatkan metrik penggunaan yang berguna tentang integrasi Anda.
• Jelajahi fulfillment lokal untuk smart home.
• Lihat sampel GitHub kami untuk mempelajari lebih lanjut.

Anda juga dapat mempelajari lebih lanjut cara menguji dan mengirimkan integrasi untuk ditinjau, termasuk proses sertifikasi untuk memublikasikan integrasi Anda kepada pengguna.