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

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

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

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

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

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

מה תפַתחו

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

מה תלמדו

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

הדרישות

• דפדפן אינטרנט, כמו Google Chrome
• מכשיר iOS או Android שמותקנת בו אפליקציית Google Home
• ‫Node.js מגרסה 24 ואילך
• חשבון לחיוב ב-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 כדי לקבל מידע נוסף.

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