ברוכים הבאים למרכז המפתחים של Google Home. זהו היעד החדש ללימוד פיתוח פעולות לבית חכם. הערה:תצטרכו להמשיך ליצור פעולות במסוף הפעולות.

דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

מה תפַתחו

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

מה תלמדו

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

מה צריך להכין

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

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

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

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

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

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

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

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

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

התחברות ל-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 תגיב בקול על כך שמשהו לא בסדר:

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

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

מרכז הבקרה של Smarthome Analytics

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

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

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

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

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

גוללים למטה לתרשים שגיאות בביצוע הזמנות ב-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:

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

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

אחרי שהרצה של 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 תוכלו לקרוא מידע נוסף.

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