對智慧型住宅進行偵錯

1. 事前準備

物聯網 (IoT) 開發人員可以建立雲端到雲端整合，讓使用者透過 Google Home 應用程式中的觸控控制選項，以及 Google 助理的語音指令控制裝置。

a4657871181b5ad2.gif

瞭解雲端到雲端整合的偵錯工具，是建立與 Google 助理的正式版整合品質的重要步驟。為了讓您輕鬆監控及偵錯，Google Cloud Platform (GCP) Metrics、Logging 和 智慧型家居測試套件可協助您找出並解決整合問題。

必要條件

建構項目

在這個程式碼研究室中，您將部署含有 2 個瑕疵的雲端到雲端整合，並將其連結至 Google 助理，然後透過智慧型家居與 Google Cloud Platform (GCP) 的「Metrics and Logging」(指標和記錄) 測試套件，對整合作業的瑕疵進行偵錯。

課程內容

  • 如何使用 GCP 指標和記錄功能，找出並解決實際工作環境問題
  • 如何使用智慧型家居測試套件找出功能和 API 問題

軟硬體需求

2. 執行有問題的應用程式

取得原始碼

按一下下方連結，即可在開發機器上下載這個程式碼研究室的範例：

...或者，您也可以從指令列複製 GitHub 存放區：

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

關於專案

洗衣機應用程式包含下列子目錄：

連結至 Firebase

在開發機器上開啟終端機，前往 washer-faulty 目錄，然後在將智慧型住宅裝置連結至 Google 助理程式碼研究室中建構的整合專案中設定 Firebase CLI：

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

部署至 Firebase

前往 functions 資料夾，然後使用 npm. 安裝所有必要的依附元件

$ cd functions
$ npm install

注意：如果您看到下列訊息，可以忽略並繼續操作。這項警告是因為一些較舊的依附元件，詳情請參閱這篇文章。

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

您已安裝依附元件並設定專案，現在可以部署有問題的洗滌機應用程式了。

$ firebase deploy

您應該會看到下列控制台輸出內容：

...

✔ Deploy complete!

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

更新 HomeGraph

在瀏覽器 (https://<firebase-project-id>.firebaseapp.com) 中開啟主機網址，即可查看網頁應用程式。在網頁 UI 中，按一下「Refresh」ae8d3b25777a5e30.png 按鈕，透過「Request Sync」更新 HomeGraph，並使用來自故障洗衣機應用程式的最新裝置中繼資料：

6f2b1344179977cf.png

開啟 Google Home 應用程式，確認你能看到名稱為「Faulty Washer」的洗衣機裝置。

e357de6a7faff925.png

3. 測試整合

部署專案後，請測試整合功能是否可控制洗衣機。

測試洗衣機

透過手機試用下列任一語音指令時，請檢查值是否有變化：

「Ok Google，打開洗衣機。」

「Ok Google，啟動洗衣機。」

「Ok Google，暫停洗衣機。」

「Ok Google，繼續執行洗衣機」

「Ok Google，停止洗衣機運作。」

當你暫停 / 繼續洗衣機運作時，Google 助理會透過語音回應發生錯誤：

「抱歉，我無法聯絡到 <專案顯示名稱>。」

如要對這個問題進行偵錯，您必須先取得更多錯誤資訊，才能縮小範圍並找出根本原因。

Smarthome Analytics 資訊主頁

如要檢查錯誤，請前往 Smarthome Analytics 資訊主頁，該資訊主頁會匯總雲端訂單履行服務的使用量和健康指標圖表：

  • 「使用率」指標會反映雲端至雲端整合功能的使用趨勢，包括每日活躍使用者人數和執行服務的總要求次數。
  • Health 指標可協助您監控雲端到雲端整合作業的異常情形，包括要求延遲時間、成功百分比和錯誤細目。

如要進一步瞭解錯誤原因，請按照下列步驟存取專案資訊主頁。

  1. 在 Developer Console 中，前往「Projects」(專案) 頁面。
  2. 選取智慧型住宅專案。
  3. 按一下左選單中的「數據分析」分頁標籤。

b1735bbe11a7aff8.png

  1. 這會帶您前往 Google Cloud 專案的資訊主頁清單。選取「Google Home Analytics - Cloud Integration」資訊主頁。

5edd3751323176dd.png

  1. 向下捲動至「Cloud Fulfillment Errors - Status Breakdown」圖表，查看醒目顯示時間範圍的錯誤代碼。

c468743c20a11c15.png

PARTNER_RESPONSE_MISSING_DEVICE 錯誤代碼會提供根本原因的提示。接著，根據錯誤代碼擷取事件記錄，以取得更多詳細資料。

存取事件記錄

如要進一步瞭解錯誤，請透過 Cloud Logging 存取 Cloud-to-cloud 整合功能的事件記錄。

在 Google Cloud Platform 中開啟「導覽選單」，然後在「作業」下方依序選取「記錄」 >「記錄檔探索工具」，即可存取專案的事件記錄。或者，您也可以在搜尋框中搜尋「Logs Explorer」。

在「Search all fields」輸入欄位中輸入查詢 PARTNER_RESPONSE_MISSING_DEVICE，然後按一下「Run Query」。系統會在「結果」部分顯示符合查詢的記錄。

747cca0f1249a5a.png

錯誤記錄會顯示智慧型家居事件，並提供錯誤詳細資料，指出：

  • 使用者採取的動作是「重新啟動洗衣機」(actionType:「STARTSTOP_UNPAUSE」)，對應到最近失敗的語音指令。
  • 相關的偵錯訊息為「JSON response does not include device.」

根據偵錯訊息，您應該檢查洗衣機應用程式為何未在 EXECUTE 回應中加入正確的裝置。

找出錯誤的根本原因

在 functions/index.js 中，找出會傳回每個指令的狀態和新裝置狀態的 EXECUTE 處理常式 (位於 onExecute 陣列中)。將裝置 ID 插入 EXECUTE 回應，取決於 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)));
     }
   }
 }

進一步檢查 updateDevice 函式如何處理洗衣機的暫停 / 繼續功能，您會發現與暫停 / 繼續指令相符的字串不正確：

index.js

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

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

修正錯誤

找出錯誤的根本原因後，您可以修正暫停 / 繼續指令的字串：

index.js

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

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

測試修正結果

使用 Firebase CLI 部署更新後的程式碼：

firebase deploy --only functions

請重試下列語音指令，你會發現在暫停 / 繼續洗衣時，Google 助理現在會正確回應。

「Ok Google，暫停洗衣機。」

=>

「好的，我會暫停洗衣機。」

「Ok Google，繼續執行洗衣機。」

=>

「我知道了，正在恢復洗衣機運作。」

你也可以透過提問，測試洗衣機目前的狀態。

「Ok Google，我的洗衣機是否開啟？」

「Ok Google，洗衣機是否運作中？」

「Ok Google，我的洗衣機正在執行哪個週期？」

4. 使用測試套件測試整合

除了手動測試之外，您還可以使用自動化的智慧型家居測試套件，根據與整合相關聯的裝置類型和特徵驗證用途。測試套件會執行一系列測試，偵測整合作業中的問題，並針對失敗的測試案例顯示資訊性訊息，以便您在深入研究事件記錄之前，加快偵錯作業。

執行智慧型住宅的測試套件

請按照下列操作說明，透過 Test Suite 測試雲端到雲端整合：

  1. 在網路瀏覽器中開啟智慧住宅測試套件。
  2. 使用右上角的按鈕登入 Google。這樣一來，測試套件就能直接將指令傳送至 Google 助理。
  3. 在「Project ID」欄位中，輸入雲端到雲端整合項目的專案 ID。然後點選「下一步」繼續。
  4. 在「測試設定」步驟中，您會看到「測試套件」列出洗衣機的裝置類型和特徵。

78ed6a1ebdb581bf.png

  1. 由於範例洗衣機應用程式沒有用於新增 / 移除 / 重新命名洗衣機的 UI，因此請停用「Test Request Sync」選項。在實際運作系統中，只要使用者新增 / 移除 / 重新命名裝置，就必須觸發「Request Sync」。
  2. 按一下「NEXT」即可開始執行測試。

測試套件執行完畢後，您可以查看測試案例的結果。您會發現兩個失敗的測試案例，並顯示相應的錯誤訊息：

5838d10631c98ed2.png

如要針對失敗的雲端到雲端整合進行偵錯，您必須先分析錯誤訊息，找出錯誤的根本原因。

分析錯誤訊息

為了協助開發人員找出根本原因，Test Suite 會針對每個失敗的測試案例顯示錯誤訊息，指出失敗的原因。

針對上述第一個失敗的測試案例，

99e4e5d06965a8a7.png

錯誤訊息指出 Test Suite 預期從雲端對雲端整合功能回報的狀態中包含 "isPause": true，但實際狀態只包含 "isPause": false。

此外，第二個失敗的測試案例錯誤訊息指出，雲端對雲整合的 QUERY 回應中含有 "isPause": true 狀態，這與雲端對雲整合中回報的狀態 "isPause": false 不同：

fdb5124102e3a37.png

根據這兩則錯誤訊息，您應該檢查整合報告是否有正確的 isPaused 值。

找出錯誤的根本原因

開啟 functions/index.js，其中包含 reportstate 函式，可透過 Report State 將狀態變更發布至 Home Graph。檢查「Report State」酬載，您會發現酬載缺少 isPaused 狀態，而這正是測試套件在失敗的測試案例中檢查的項目。

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: true,
                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,
      });
      ...
    });

修正錯誤

找出錯誤的根本原因後，請將 isPaused 狀態新增至「Report State」酬載，以修訂 functions/index.js：

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: true,
                on: snapshot.OnOff.on,
                isPaused: snapshot.StartStop.isPaused,
                isRunning: snapshot.StartStop.isRunning,
                currentRunCycle: [{
                  currentCycle: 'rinse',
                  nextCycle: 'spin',
                  lang: 'en',
                }],
                currentTotalRemainingTime: 1212,
                currentCycleRemainingTime: 301,
              },
            },
          },
        },
      };
      ...
    });

測試修正結果

使用 Firebase CLI 部署更新後的程式碼：

$ firebase deploy --only functions

重新執行智慧型家居的測試套件，您會發現所有測試案例都已通過。

148837f85d377dd6.png

5. 恭喜

17d485868a6771bc.png

恭喜！您已成功瞭解如何透過智慧型住宅測試套件和 GCP Metrics 和記錄功能，排解雲端到雲端整合問題。

瞭解詳情

請參考本程式碼研究室的內容，嘗試下列練習，並探索其他資源：

您也可以進一步瞭解如何測試及提交整合項目供審查，包括向使用者發布整合項目的認證程序。