對智慧型住宅進行偵錯

1. 事前準備

身為物聯網 (IoT) 的開發人員,您可以打造智慧型住宅動作,讓使用者能透過 Google Home 應用程式中的觸控設定,以及搭配 Google 助理下達語音指令操控自己的裝置。

a4657871181b5ad2.gif

學習智慧型住宅動作的偵錯工具是與 Google 助理建構品質整合工作的重要步驟。為協助您找出並解決動作的問題,我們準備了 Google Cloud Platform (GCP) 指標LoggingTest Suite for 智慧型住宅

必要條件

建構項目

在本程式碼研究室中,您將部署有 2 項瑕疵的智慧型住宅動作並連結至 Google 助理,然後透過 Test Suite 為智慧型住宅和 Google Cloud Platform (GCP) 指標和 Logging 偵錯動作的瑕疵。

課程內容

  • 如何使用 GCP 指標和 Logging 找出並解決正式環境問題
  • 如何使用智慧型住宅的 Test Suite 找出功能和 API 問題

軟硬體需求

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

取得原始碼

點選下方連結,即可在開發機器上下載這個程式碼研究室的範例:

...或透過指令列複製 GitHub 存放區:

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

關於專案

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

連結至 Firebase

在開發機器上開啟終端機。前往 washer-faulty 目錄,然後使用「將智慧住宅裝置連結至 Google 助理」程式碼研究室中內建的「動作」專案設定 Firebase CLI:

$ cd washer-faulty
$ firebase use <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/<project-id>/overview
Hosting URL: https://<project-id>.firebaseapp.com

更新 HomeGraph

在瀏覽器中開啟「Hosting URL」 (https://<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 資訊主頁查看錯誤,其中匯總了您雲端執行要求的使用情形和健康狀態指標圖表:

  • 「用量」指標反映智慧型住宅動作的使用情形趨勢,包括每日活躍使用者人數,以及完成要求的總要求次數。
  • 「健康」指標可協助您監控智慧型住宅動作的異常情況,包括要求延遲時間、成功百分比和錯誤細目。

如要縮小錯誤原因,請按照下列步驟存取專案資訊主頁。

  1. 動作控制台中,前往「專案」頁面。
  2. 選取智慧型住宅專案。
  3. 選擇「Analytics (分析)」分頁標籤,然後點選「前往 Google Cloud Platform」

b1735bbe11a7aff8.png

  1. 系統會將您導向 Google Cloud 中專案的資訊主頁清單。選取「Google Home Analytics - 雲端整合」資訊主頁。

5edd3751323176dd.png

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

c468743c20a11c15.png

PARTNER_RESPONSE_MISSING_DEVICE 錯誤代碼會提供根本原因的提示。接著,根據錯誤代碼擷取事件記錄以瞭解詳情。

存取事件記錄

如要進一步瞭解這個錯誤,請透過 Cloud Logging 存取智慧居家動作的事件記錄。

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

在「Query」區段中,輸入查詢 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. 使用測試套件測試動作

除了手動測試,您還可以使用自動化的智慧型住宅測試套件,根據與動作相關的裝置類型和特徵驗證用途。「測試套件」會執行一系列測試來偵測動作中的問題,並顯示失敗測試案例的相關資訊,以加快偵錯速度,然後再深入查看事件記錄。

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

請按照下列操作說明,使用「測試套件」測試智慧住宅動作:

  1. 在網路瀏覽器中開啟測試智慧型住宅套件
  2. 點選右上角的按鈕即可登入 Google。這麼做可讓測試套件直接將指令傳送給 Google 助理。
  3. 在「專案 ID」欄位中,輸入智慧型住宅動作的專案 ID。然後點選「下一步」繼續操作。
  4. 在「Test Settings」步驟中,系統會顯示測試套件,並列出洗衣機的裝置類型和特徵。

78ed6a1ebdb581bf.png

  1. 停用「Test Request Sync」選項,因為範例應用程式沒有可新增 / 移除 / 重新命名洗衣機的 UI。在工作系統中,每當使用者新增 / 移除 / 重新命名裝置時,您都必須觸發 Request Sync
  2. 點選「下一步」開始執行測試。

測試套件執行完畢之後,請查看測試案例的結果。您會發現兩筆失敗的測試案例,以及對應的錯誤訊息:

5838d10631c98ed2.png

如要對智慧型住宅動作失敗進行偵錯,您需要先分析錯誤訊息來找出錯誤的根本原因。

分析錯誤訊息

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

以上方第一個失敗的測試案例來說

99e4e5d06965a8a7.png

錯誤訊息表示測試套件預期在智慧型住宅動作回報的狀態中,預期有 "isPause": true,但實際狀態只會包含 "isPause": false

此外,第二個失敗的測試案例的錯誤訊息會指出智慧型住宅動作的 QUERY 回應中,其中的狀態包含 "isPause": true,這與智慧型住宅動作回報的狀態不同:"isPause": false

fdb5124102e3a37.png

根據兩則錯誤訊息,您應該檢查動作回報的 isPaused 是否為正確的值。

找出錯誤的根本原因

開啟 functions/index.js,其中包含 reportstate 函式,可透過報告狀態將狀態變更發布至 Home Graph。檢查報表狀態酬載,就會發現酬載缺少 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 狀態新增至報表狀態酬載,修正 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

恭喜!您已學會如何透過 Test Suite 排解智慧型住宅及 GCP 指標和記錄功能的智慧住宅動作問題。

瞭解詳情

建構本程式碼研究室後,您可以嘗試下列練習並瀏覽其他資源:

您也可以進一步瞭解如何測試並提交動作以供審查,包括向使用者發布動作的認證程序。