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

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

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

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

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

• לקרוא את המדריך למפתחים בנושא יצירת שילוב בין ענן לענן
• הפעלת ה-codelab חיבור מכשירים לבית חכם אל Google Assistant

מה תפַתחו

ב-codelab הזה תפרסו אינטגרציה בין ענן לענן עם 2 פגמים, ותקשרו אותה ל-Assistant. לאחר מכן תנפו את הפגמים באינטגרציה באמצעות Test Suite for smart home & Google Cloud Platform (GCP) Metrics and Logging.

מה תלמדו

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

הדרישות

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

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

קבלת קוד המקור

כדי להוריד את הדוגמה ל-codelab הזה למחשב הפיתוח, לוחצים על הקישור הבא:

file_downloadהורדת קוד המקור

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

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

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

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

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

התחברות אל Firebase

פותחים טרמינל במחשב הפיתוח. עוברים אל הספרייה washer-faulty ומגדירים את Firebase CLI עם פרויקט השילוב שנוצר ב-codelab Connect smart home devices to the Google Assistant:

$ 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

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

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

3. בדיקת השילוב

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

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

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

‫"Ok Google, turn on my washer" (הפעלת מכונת הכביסה)

‫"Ok Google, start my washer"‏ (הפעלת מכונת הכביסה)

‫"Ok Google, pause my washer" (הפעלת מכונת הכביסה)

‫"Ok Google, resume my washer" (הפעלת מכונת הכביסה)

"Ok Google, stop my washer"

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

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

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

מרכז השליטה של ניתוח נתונים בבית חכם

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

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

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

1. במסוף המפתחים, עוברים לדף Projects.
2. בוחרים את הפרויקט של הבית החכם.
3. בתפריט הימני, לוחצים על הכרטיסייה Analytics.

4. תועברו לרשימה של לוחות בקרה של הפרויקט ב-Google Cloud. בוחרים בלוח הבקרה Google Home Analytics - Cloud Integration (ניתוח נתונים של Google Home – שילוב עם הענן).

5. גוללים למטה לתרשים Cloud Fulfillment Errors - Status Breakdown כדי לראות את קודי השגיאה של טווח הזמן המודגש.

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

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

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

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

בשדה הקלט חיפוש בכל השדות, מזינים את השאילתה PARTNER_RESPONSE_MISSING_DEVICE ולוחצים על הפעלת שאילתה. היומנים שתואמים לשאילתה מוצגים בקטע 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':
      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);
};

תיקון השגיאה

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

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

בדיקת התיקון

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

firebase deploy --only functions

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

‫"Ok Google, pause my washer"

=>

"בטח, אני משבית את מכונת הכביסה".

‫"Ok Google, resume my washer" (הפעלה מחדש של מכונת הכביסה).

=>

"הבנתי, אני מפעיל מחדש את מכונת הכביסה".

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

‫"Ok Google, is my washer on?"

‫"Ok Google, is my washer running?"

‫"Ok Google, באיזה מחזור הכביסה פועלת?"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

זיהוי הסיבה הבסיסית לשגיאה

פותחים את functions/index.js, שמכיל את הפונקציה reportstate שמפרסמת שינויים בסטטוס ב-Home Graph באמצעות Report State. בודקים את מטען הייעודי (payload) של Report State (סטטוס הדוח) ורואים שחסר בו הסטטוס isPaused, בדיוק מה שנבדק ב-Test Suite במקרים של בדיקות שנכשלו.

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

תיקון השגיאה

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

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

בדיקת התיקון

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

$ firebase deploy --only functions

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

5. מזל טוב

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

מידע נוסף

כדאי לנסות את התרגילים הבאים ולעיין במשאבים נוספים:

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

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