ברוכים הבאים למרכז המפתחים של Google Home. זהו היעד החדש ללימוד פיתוח פעולות לבית חכם. הערה:תצטרכו להמשיך ליצור פעולות במסוף הפעולות.

דף זה תורגם על ידי Cloud Translation API.

ניפוי באגים בבית החכם

1. לפני שמתחילים

מפתחים של "אינטרנט של דברים" (IoT) יכולים ליצור פעולות בית חכם שנותנות למשתמשים את היכולת לשלוט במכשירים שלהם באמצעות פקדי מגע באפליקציית Google Home ופקודות קוליות עם Google Assistant.

למידת הכלים לניפוי באגים בפעולות לבית חכם היא שלב חשוב בתהליך ההטמעה של איכות הייצור עם Google Assistant. כדי לאפשר מעקב וניפוי באגים בקלות, המדדים של Google Cloud Platform (GCP), Logging ו-Test Suite לבית החכם זמינים כדי לעזור לך לזהות ולפתור בעיות בפעולות.

דרישות מוקדמות

מידע נוסף במדריך למפתחים בנושא יצירת פעולה בבית חכם
הפעלת הקוד של חיבור מכשירים לבית חכם אל Google Assistant

מה תפַתחו

בשיעור ה-codelab הזה צריך לפרוס פעולת בית חכם עם 2 פגמים ולחבר אותה ל-Assistant, ולאחר מכן לנפות באגים בפגמים בפעולה דרך Test Suite למדדים ולרישום ב-Google Cloud Platform וב-Google Cloud Platform (GCP).

מה תלמדו

איך משתמשים במדדים וברישום של GCP כדי לזהות ולפתור בעיות ייצור
איך משתמשים ב-Test Suite לבית החכם כדי לזהות בעיות בפונקציונליות וב-API

מה צריך להכין

דפדפן אינטרנט, כמו Google Chrome
מכשיר iOS או Android שמותקנת בו אפליקציית Google Home.
Node.js בגרסה 10.16 ואילך
חשבון לחיוב ב-Google Cloud

2. הפעילו את האפליקציה הפגומה

איך מקבלים את קוד המקור

כדי להוריד למחשב הפיתוח את הדוגמה של Codelab זה, יש ללחוץ על הקישור הבא:

...או שאפשר לשכפל את המאגר של GitHub משורת הפקודה:

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

מידע על הפרויקט

אפליקציית מכונת הכביסה מכילה את ספריות המשנה הבאות:

public: ממשק משתמש חזיתי שמאפשר לשלוט בקלות במצב של מכונת הכביסה החכמה ולנטר אותה.
functions: שירות ענן שהוטמע באופן מלא שמנהל את מכונת הכביסה החכמה באמצעות Cloud Functions for Firebase ומסד נתונים בזמן אמת ב-Firebase.

קישור ל-Firebase

מסוף פתוח במחשב הפיתוח. עוברים לספרייה washer-faulty ומגדירים את ה-CLI של Firebase בפרויקט הפעולות המובנה בחיבור מכשירים לבית חכם אל ה-codelab של Google Assistant:

$ 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

פותחים את כתובת ה-URL לאירוח בדפדפן (https://<project-id>.firebaseapp.com) כדי להציג את אפליקציית האינטרנט. בממשק המשתמש של האינטרנט, לוחצים על הלחצן רענון כדי לעדכן את HomeGraph דרך בקשת סנכרון עם המטא-נתונים העדכניים של המכשיר מהאפליקציה הפגומה של מכונת הכביסה:

פותחים את אפליקציית Google Home ומוודאים שאפשר לראות את מכונת הכביסה בשם Faulty Washer.

3. בדיקת הפעולה

לאחר פריסת הפרויקט, בודקים שהפעולה שולטת במכונת הכביסה.

בדיקת מכונת הכביסה

יש לבדוק את השינוי בערך כשמנסים אחת מהפקודות הקוליות הבאות בטלפון:

"Ok Google, turn on my weather"

"Ok Google, start my weather"

"Ok Google, Pause my Waher"

"Ok Google, בהתאמה שלי למכונת הכביסה"

"Ok Google, stop my washer"

Assistant מגיבה שמשהו השתבש באמצעות הקול כשמשהים או מחדשים את מכונת הכביסה:

"מצטערים, לא הצלחתי להגיע אל <שם התצוגה של הפרויקט>".

כדי לנפות את הבאגים שגרמו לבעיה, צריך תחילה מידע נוסף על השגיאה כדי לצמצם ולזהות את שורש הבעיה.

מרכז הבקרה של Analytics ל-Smarthome

מקום טוב לבדוק את השגיאות הוא מרכז הבקרה של Smarthome Analytics, שבו מופיעים תרשימים של מדדי שימוש ותקינות למילוי ההזמנות שלכם בענן:

מדדי השימוש משקפים את מגמת השימוש בפעולה בבית החכם, כולל מספר המשתמשים הפעילים ביום והמספר הכולל של הבקשות למילוי הבקשה.
מדדי תקינות עוזרים לכם לעקוב אחרי אירועי חריגה בפעולה בבית החכם. המדדים האלה כוללים נתונים על זמן האחזור של הבקשות, אחוז ההצלחה ופירוט השגיאות.

כדי לצמצם את הגורם לשגיאה, פועלים לפי השלבים הבאים כדי לגשת למרכז הבקרה של הפרויקט.

במסוף הפעולות, נכנסים לדף Projects.
בוחרים את הפרויקט לבית החכם.
בוחרים בכרטיסייה Analytics ולוחצים על מעבר אל Google Cloud Platform.

תוצג רשימה של מרכזי בקרה לפרויקט שלכם ב-Google Cloud. בוחרים את לוח הבקרה Google Home Analytics - Cloud Integration (שילוב של Google Home Analytics).

גוללים למטה לתרשים שגיאות מילוי הזמנות בענן – פירוט סטטוס כדי להציג את קודי השגיאות של טווח הזמן המודגש.

קוד השגיאה PARTNER_RESPONSE_MISSING_DEVICE מספק רמז לשורש הבעיה. בשלב הבא, מאחזרים יומני אירועים על סמך קוד השגיאה, כדי לקבל פרטים נוספים.

גישה ליומני האירועים

כדי לקבל פרטים נוספים על השגיאה, יש לגשת ליומני האירועים של הפעולות בבית החכם באמצעות Cloud Logging.

פותחים את תפריט הניווט ב-Google Cloud Platform, ובקטע Operations, בוחרים באפשרות Logging > Logs Explorer כדי לגשת ליומני האירועים של הפרויקט. לחלופין, אפשר לחפש את Logs Explorer בתיבת החיפוש.

בקטע Query (שאילתה), מזינים את השאילתה PARTNER_RESPONSE_MISSING_DEVICE ולוחצים על Run Query. היומנים שתואמים לשאילתה מוצגים בקטע Query results.

ביומן השגיאות מוצג אירוע בבית חכם עם פרטי השגיאה הבאים:

פעולת המשתמש שננקטה היא 'חידוש מכונת הכביסה' (actionType: 'STARTSTOP_UNPAUSE'), בהתאם לפקודה הקולית שנכשלה לאחרונה.
ההודעה המשויכת לניפוי באגים היא 'JSON response does not include device.'

על סמך ההודעה לניפוי באגים, צריך לבדוק למה האפליקציה של מכונת הכביסה לא כוללת את המכשיר הנכון בתגובה של EXECUTE.

זיהוי שורש הבעיה

ב-functions/index.js, מאתרים את ה-handler של EXECUTE (במערך onExecute) שמחזיר את הסטטוס של כל פקודה ואת המצב החדש של המכשיר. ההוספה של מזהי מכשירים לתגובה של 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);
};

בדיקת התיקון

פורסים את הקוד המעודכן באמצעות ה-CLI של Firebase:

firebase deploy --only functions

אפשר לנסות לבצע שוב את הפקודות הקוליות הבאות, ותראה ש-Assistant מגיבה כראוי עכשיו כשמשהים או ממשיכים את השימוש במכונת הכביסה.

"Ok Google, paused my Waher".

"כן, אני רוצה להשהות את מכונת הכביסה".

"Ok Google, בהתאמה שלי למכונת הכביסה".

"הבנתי, אנחנו משדרגים את המכונת כביסה".

אפשר גם לשאול שאלות כדי לבדוק את המצב הנוכחי של מכונת הכביסה.

"Ok Google, is my washer on?"

"Ok Google, is my Wahr running?"

"Ok Google, what cycle is my Waher on?"

4. בדיקת הפעולה באמצעות חבילת הבדיקה

בנוסף לביצוע בדיקה ידנית, אתם יכולים להשתמש במקבץ הבדיקות האוטומטי לבית החכם כדי לאמת תרחישים לדוגמה על סמך סוגי המכשירים והמאפיינים שמשויכים לפעולה. חבילת הבדיקה מריצה סדרה של בדיקות כדי לזהות בעיות בפעולה, ומציגה הודעות אינפורמטיביות למקרי בדיקה שנכשלו כדי לזרז את ניפוי הבאגים לפני שאתם צוללים ליומני האירועים.

הפעלה של חבילת הבדיקה לבית חכם

כדי לבדוק את הפעולה של הבית החכם באמצעות Test Suite, עליכם לפעול לפי ההוראות הבאות:

בדפדפן האינטרנט, פותחים את חבילת הבדיקה לבית חכם.
נכנסים לחשבון Google באמצעות הלחצן שבפינה השמאלית העליונה. ההרשאה הזו מאפשרת לחבילת הבדיקה לשלוח את הפקודות ישירות אל Google Assistant.
בשדה Project ID מזינים את מזהה הפרויקט של פעולת הבית החכם. לאחר מכן, לוחצים על הבא כדי להמשיך.
בשלב Test Settings תופיע רשימה של סוגי המכשיר והתכונות של מכונת הכביסה.

משביתים את האפשרות בדיקת הבקשה לסנכרון כי באפליקציה של מכונת הכביסה לדוגמה אין ממשק משתמש שאפשר להוסיף, להסיר או לשנות את השם של מכונת הכביסה. במערכת ייצור, צריך להפעיל בקשת סנכרון בכל פעם שמשתמש מוסיף מכשירים, מסיר אותם או משנה את השם שלהם.
לוחצים על הבא כדי להתחיל להריץ את הבדיקה.

כשחבילת הבדיקה תסתיים, תוכלו לראות את התוצאות של מקרי הבדיקה. יופיעו שני מקרי בדיקה שנכשלו עם הודעת השגיאה המתאימה:

כדי לנפות באגים בפעולה של הבית החכם לגבי הכשל, צריך קודם לנתח את הודעת השגיאה ולזהות את שורש הבעיה.

הודעת השגיאה 'ניתוח'

כדי לעזור למפתחים לזהות את שורש הבעיה, קבוצת הבדיקה מציגה הודעות שגיאה לכל מקרה בדיקה שנכשל, שמציינות את הסיבה לכשל.

לגבי מקרה הבדיקה הראשון שנכשל למעלה,

הודעת השגיאה שלה מציינת ש-Test Suite מצפה ל"isPause": true במדינות שדווחו לגבי הפעולה בבית החכם, אבל המצבים בפועל כוללים רק "isPause": false.

בנוסף, הודעת השגיאה השנייה של מקרה הבדיקה שנכשלה מציינת שהמצבים שצוינו בתגובה QUERY ביחס לפעולה בבית החכם כוללים את "isPause": true. המצב הזה שונה מ-"isPause": false במצבים שדווחו מהפעולה בבית החכם:

לפי שתי הודעות השגיאה, צריך לבדוק אם בדוחות הפעולות מופיע הערך הנכון isPaused.

זיהוי שורש הבעיה

פתח את functions/index.js, שמכיל את הפונקציה reportstate שמעדכנת את מצבה בתרשים דף הבית דרך מצב הדוח. בודקים את המטען הייעודי (payload) של מצב הדוח כדי לגלות שבמטען הייעודי חסר המצב 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,
      });
      ...
    });

תיקון השגיאה

עכשיו, אחרי שזיהיתם את שורש הבעיה, צריך לתקן את functions/index.js על ידי הוספת המצב isPaused למטען הייעודי (payload) של מצב הדוח:

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

בדיקת התיקון

פורסים את הקוד המעודכן באמצעות ה-CLI של Firebase:

$ firebase deploy --only functions

הפעילו מחדש את חבילת הבדיקה לבית החכם. תראו שכל מקרי הבדיקה עברו.

5. מזל טוב

כל הכבוד! למדתם בהצלחה איך לפתור בעיות שקשורות לפעולות בבית החכם באמצעות Test Suite למדדים ולרישום ביומן של בית חכם ו-GCP.

מידע נוסף

כדי לפתח את Codelab, כדאי לנסות את התרגילים הבאים ומשאבים נוספים:

אפשר להוסיף למכשיר עוד תכונות נתמכות ולבדוק אותן באמצעות Test Suite.
כדי לקבל מדדי שימוש מועילים לגבי הפעולה, אתם יכולים ליצור מרכזי בקרה, להגדיר התראות ולגשת לנתוני מדדים באופן פרוגרמטי.
למידע על מילוי הזמנות בחנות מקומית לבית חכם.
רוצים לקבל מידע נוסף? אתם מוזמנים לעיין בדוגמה שלנו ל-GitHub.

אפשר גם לעיין במידע נוסף על בדיקה ושליחה של פעולה לבדיקה, כולל תהליך האישור לפרסום הפעולה למשתמשים.