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

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

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

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

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

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

מה תפַתחו

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

מה תלמדו

• איך משתמשים במדדים וברישום ביומן ב-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. ב-Developer Console, עוברים לדף 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. בדיקת השילוב באמצעות חבילת הבדיקות

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

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

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

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

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

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

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

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

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

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

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

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

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

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

פותחים את functions/index.js, שמכיל את הפונקציה reportstate ששולחת שינויים במצב ל-Home Graph באמצעות Report State. בודקים את מטען הייעודי (payload) של 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: 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.

מידע נוסף

בהתבסס על Codelab זה, נסו את התרגילים הבאים וחקרו משאבים נוספים:

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

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