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

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

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

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

לימוד הכלים לניפוי באגים בשילובים של Cloud-to-cloud הוא שלב חשוב ביצירת שילוב באיכות ייצור עם Google Assistant. כדי לעזור לכם לזהות ולפתור בעיות בשילובים, אתם יכולים להשתמש במדדי Google Cloud Platform‏ (GCP), ברישום ביומן וב-Test Suite for smart home.

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

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

מה תפַתחו

בקודלאב הזה פורסים אינטגרציה מענן לענן עם 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 עם פרויקט השילוב שיצרתם בקודלאב 'חיבור מכשירי בית חכם ל-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 תגיב בקול על כך שמשהו לא בסדר:

"Sorry, I couldn't reach <project display name>."

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

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

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

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

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

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

4. תוצג רשימה של לוחות בקרה לפרויקט ב-Google Cloud. בוחרים בלוח הבקרה Google Home Analytics – Cloud Integration.

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

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

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

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

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

בשדה הקלט Search all fields, מזינים את השאילתה PARTNER_RESPONSE_MISSING_DEVICE ולוחצים על Run Query. היומנים שתואמים לשאילתה מוצגים בקטע תוצאות.

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

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

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

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

ב-functions/index.js, מחפשים את הטיפול 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, pause my washer"

=>

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

"Ok Google, resume my washer"

=>

"הבנתי, ממשיכים את הכביסה."

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

"Ok Google, is my washer on?"

"Ok Google, is my washer running?"

"Ok Google, what cycle is my washer on?‎"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 הזה, כדאי לנסות את התרגילים הבאים ולעיין במשאבים נוספים:

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

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