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

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

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

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

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

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

מה תפַתחו

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

מה תלמדו

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

לעדכון תרשים הבית

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

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

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

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

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

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

"Ok Google, turn on my worker".

"Ok Google, start my instance".

"Ok Google, Pause my method. "

"Ok Google, Resume my – מכונת הכביסה"

"Ok Google, stop my worker"

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

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

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

מרכז הבקרה של Analytics בית חכם

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

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

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

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

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

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

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

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

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

פותחים את תפריט הניווט ב-Google Cloud Platform, ובקטע פעולות בוחרים באפשרות 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, Pause my ללחוץ על 'מכונת הכביסה'.

=&gt;

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

"Ok Google, Resume my instance".

=&gt;

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

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

"Ok Google, is my הייתה מכונת כביסה?"

"Ok Google, האם מכונת הכביסה פועלת?"

"Ok Google, whatcycle is my הייתה מכונת כביסה?"

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

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

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

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

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

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

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

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

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

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

בתרחיש הראשון שצוין למעלה, שנכשל:

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

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

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

מזהים את שורש הבעיה לשגיאה

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

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

5. מזל טוב

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

מידע נוסף

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

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

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