ניפוי באגים בשילובים של Matter

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

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

בקודלאב הזה נסביר על שלושת הרכיבים העיקריים של Matter. לכל אחת מהמערכות האלה, Google מספקת למפתחים ניתוח נתונים לפתרון בעיות שנאסף מטלפונים ומרכזיות:

הפעלה, ביצוע, עדכון OTA

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

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

  • להשלים את המדריך תחילת העבודה עם Matter עם פרויקט Matter פעיל והגדרת מכשיר
  • טלפון Android שאפשר לחבר לתחנת העבודה (ליומני ADB)

מה תלמדו

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

2. הצגת ניתוח הנתונים של Google Home

מעקב אחרי הביצועים הוא חיוני לשילוב מוצלח עם הסביבה העסקית של Google Home. אנחנו מספקים קבוצה של כלי מעקב למפתחי בתים חכמים ב-Google Cloud Platform. אתם יכולים להשתמש בכלים האלה כדי למדוד את ביצועי הפרויקט.

גישה למדדי פרויקט

  • השלב הראשון לגישה לנתונים הוא לבדוק את לוחות הבקרה של Google Home. כדי לעשות זאת, נכנסים למסוף Google Cloud ועוברים אל Operations (פעולות) > Monitoring (מעקב) > Dashboards (לוחות בקרה).

יש כמה מרכזי בקרה שזמינים לפרויקט שלך (כולל מוצרי GCP אחרים). מרכזי הבקרה שסופקו לבית החכם כוללים את הקידומת של Google Home Analytics.

לוחות הבקרה של Google Home Analytics

כרגע יש לנו מרכז בקרה כללי שמכסה את כל הפרויקט, וגם מרכזי בקרה לשילובים ספציפיים (Cloud,‏ Local,‏ Matter) או לסוגים ספציפיים של מכשירים (מצלמות). לוחות הבקרה האלה מכילים נתונים רק אם יש לכם שילוב מהסוג המתאים, וגם פרויקט פעיל שמטפל בבקשות.

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

פירוט של שיעור ההצלחה, זמן האחזור וסוג המכשיר

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

חשוב לזכור שתצוגת ברירת המחדל עם התרשימים שמוצגים במרכזי הבקרה של Google Home Analytics היא רק תצוגה שיצרנו לפרויקט שלכם באמצעות נתוני מדדי הבית החכם. אפשר גם להשתמש ב-Metrics Explorer כדי ליצור תרשימים משלכם מאותו בסיס של מדדים ולשמור אותם במרכזי הבקרה המותאמים אישית.

גישה ליומני שגיאות

Logs Explorer הוא אוסף כלים לעבודה עם יומני אירועים שנוצרו בפרויקט. אפשר לגשת אליו דרך מסוף Google Cloud, בדף Operations > Logging > Logs Explorer.

כשפותחים את Logs Explorer, מופיעה תצוגה שנראית כך:

Logs Explorer

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

3. ניפוי באגים בבעיות שקשורות להפעלה

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

במהלך הזמנת המכשיר, מתרחשת קבוצה של אינטראקציות בין המכשיר בתקן Matter, אפליקציית Google Home ומארג תקן Matter. בתמונה הבאה מוצגים חלק מהאירועים האלה:

אירועי הזמנת Matter

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

שימוש ב-Google Home Analytics

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

התרשימים בלוח הבקרה הזה מספקים נתונים על הפעלת המכשירים:

מדדים של הפעלת מכשיר

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

תנאי השימוש בשירות:

  • COMMISSIONING_STARTED
  • ONBOARDING_PAYLOAD_GENERATED
  • LOCAL_DISCOVERY_SUCCESSFUL
  • PASE_CONNECTION_SUCCESSFUL
  • NOC_ADDED_SUCCESSFULLY
  • COMMISSIONING_COMPLETE

כדי להציג גרסה מפורטת של האירועים האלה, עוברים אל Operations > Logging > Logs Explorer. כדי לסנן שגיאות שקשורות ליצירת נכסים, אפשר לחפש את הערך clientUpdateLog בשילוב עם הערך severity>=ERROR בשדה השאילתה.

יומן שגיאות של הפעלה ב-Matter נראה כך:

{
  "insertId": "1a32ry0f6xpzzn",
  "jsonPayload": {
    "clientUpdateLog": {
      "MatterUpdate": {
        "reportedProductId": 55,
        "sessionId": "1584879052892229997",
        "reportedVendorId": 4800,
        "commissioningState": "GENERIC_COMMISSIONING_ERROR",
        "status": "GENERIC_ERROR"
      }
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "<project-id>"
    }
  },
  "timestamp": "2023-03-01T07:09:55.216425297Z",
  "severity": "ERROR",
  "logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2023-03-01T07:09:55.216425297Z"
}

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

שימוש במדדים מ-Google Home Analytics נותן לכם מושג ראשוני בשלב שבו עשויה להתרחש הבעיה. כדי למצוא את שורש הבעיה בשגיאות שקשורות להפעלת המכשיר, לפעמים צריך לבצע ניפוי באגים נוסף באמצעות היומנים שנוצרו על ידי המכשיר הנייד ששימש בתהליך ההפעלה. לשם כך, צריך את Android Debug Bridge.

שימוש בגשר ניפוי הבאגים של Android (ADB)

דרך נוספת לפתרון בעיות בהפעלה היא להשתמש בכלי שורת הפקודה Android Debug Bridge‏ (ADB). מאחר שההפעלה מתבצעת בעיקר בין המכשיר הנייד לבין מכשיר Matter, אפשר להשתמש בכלי ADB כדי לגשת ליומנים שנוצרו על ידי אפליקציית Google Home במהלך ההפעלה.

התקנת כלי הפלטפורמה

ADB מגיע כחלק מ-Android SDK Platform Tools, שאפשר להתקין באמצעות Android Studio או באמצעות הכלי בשורת הפקודה sdkmanager.

אחרי שתסיימו להתקין את הכלים של הפלטפורמה במערכת, תוכלו לאמת את ADB על ידי בדיקת מספר הגרסה מהמסוף באמצעות הפקודה הבאה:

$ adb -- version

תצוגה זו אמורה להציג את מספר הגרסה של כלי העזר המותקן של ADB, ללא שגיאות.

הפעלת ניפוי באגים ב-USB

בשלב הבא מפעילים את ניפוי הבאגים ב-USB במכשיר Android.

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

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

אחזור מזהה המכשיר

  1. מריצים את שרת ה-ADB באמצעות הפקודה הבאה:
$ adb start-server
  1. מחברים את הטלפון למחשב שבו פועל שרת ADB.

יכול להיות שתופיע בטלפון הודעת אזהרה לגבי ניפוי באגים ב-USB, עם שאלה אם רוצים לאפשר למחשב לגשת למידע מהטלפון:

הנחיה לניפוי באגים ב-USB

  1. אם מופיעה הודעת האזהרה הזו, לוחצים על אישור.
  2. כדי לבדוק אם למחשב יש גישה לטלפון דרך ADB, שולחים פקודת רשימת מכשירים מהטרמינל באמצעות הפקודה הבאה:
$ adb devices

התשובה אמורה להיראות כך:

List of devices attached
<phone-id>    device

התג <phone-id> הוא מחרוזת אלפאנומרית שמזהה את המכשיר שלכם באופן ייחודי.

  1. חשוב לזכור את הערך של <phone-id> לשימוש בשלבים הבאים.

איסוף פרטי המערכת

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

  • כדי לבדוק את גרסת מערכת ההפעלה של Android:
$ adb -s <phone-id> shell getprop ro.build.version.release
  • כדי לבדוק את הגרסה של אפליקציית Google Home:
$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName
  • כדי לבדוק את הגרסה של Google Play Services:
$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"
  • כדי לבדוק אם מודול הבקרה של Home או Matter מותקן דרך Play Services:
$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"

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

איסוף יומני שגיאות

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

  1. כדי להריץ את הפקודה הבאה, מריצים את ה-<phone-id> וגם את השדה <file-name> שבו היומנים יישמרו במחשב (למשל, debug_file.txt).
$ adb -s <phone-id> logcat > <file-name>

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

ממשיכים בשלבים להגדרת המכשיר עם Matter.

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

עכשיו היומנים אמורים להיות מאוחסנים בקובץ היומן <file-name>. התהליך הזה מתעד יומנים מכל תהליך ריצה שמתנהל במעקב במכשיר, ולכן הקובץ יכלול הרבה יומנים. לכן, תמיד כדאי להשתמש ביומני האלה על ידי חיפוש הרשומות הנחוצות.

ניתוח יומני השגיאות

תהליכי ההפעלה מטופלים באמצעות מערכת משנה שנקראת MatterCommissioner ב-GHA.

  1. בהתאם לאסטרטגיה הראשית שמשמשת לניתוח שגיאות בהפעלה, מחפשים שגיאות שנוצרו על ידי מערכת המשנה MatterCommissioner באמצעות הפקודה הבאה:
$ grep "MatterCommissioner" <file-name>

הפלט שנוצר מכיל את האירועים מתהליך ההזמנה.

  1. אם מכשיר Matter משתמש ב-Thread, אפשר גם לחפש שגיאות שנוצרו על ידי מערכת המשנה של Thread באמצעות הפקודה הבאה:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

בזמן הניתוח של קובץ היומן שנוצר בתהליך ניפוי הבאגים ב-ADB, כדאי גם לחפש תבניות מסוימות. הרבה שגיאות הזמנה כוללות את המחרוזת 'commissioning failure' בהודעת השגיאה.

  1. מחפשים הודעה על כשל בהפעלה באמצעות הפקודה הבאה:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"

4. ניפוי באגים בבעיות שקשורות לשליטה במכשיר

אחרי שהמשתמשים מגדירים ומפעילים מכשירי Matter בסביבה של Google Home, הם יכולים להשתמש בפקודות קוליות באמצעות Google Assistant (לדוגמה, "Ok Google, turn on the lights in my living room") או באמצעות ממשק המשתמש באפליקציית Home או במכשירי המסך של Google Nest.

מאחר ש-Matter מתווך את מפרט הבקרה בין מכשירי הקצה לבין Google Hubs, צפויות להיות פחות שגיאות בצד הבקרה של המכשיר. בכל מקרה, אנחנו מספקים מדדים ויומנים לניפוי באגים במקרים כאלה.

שימוש במדדים

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

תרשימי פירוט של הצלחה, זמן אחזור ושגיאות

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

שימוש ביומנים

כל בעיה בשליטה במכשיר Matter יוצרת גם יומן שגיאות במערכת. כדי לסנן את השגיאות האלה ב-Logs Explorer, מחפשים את הביטוי 'executionLog'.

יומני השגיאות של בקרת המכשירים ב-Matter נראים כך:

{
  "insertId": "1a32ry0f6xpzzn",
  "jsonPayload": {
    "executionLog": {
      "executionResults": [
        {
          "executionType": "MATTER",
          "latencyMsec": "6000",
          "actionResults": [
            {
              "action": {
                "actionType": "ONOFF_OFF",
                "trait": "TRAIT_ON_OFF"
              },
              "status": {
                "externalDebugString": "No message was received before the deadline.",
                "statusType": "RESPONSE_TIMEOUT",
                "fallbackToCloud": false,
                "isSuccess": false
              },
              "device": {
                "deviceType": "OUTLET"
              }
            }
          ],
          "requestId": "1487232799486580805"
        }
      ]
    },
    "locale": "en-US"
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "<project-id>"
    }
  },
  "timestamp": "2023-03-01T15:47:27.311673018Z",
  "severity": "ERROR",
  "logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2023-03-01T15:47:27.311673018Z"
}

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

5. ניפוי באגים בתכונות אחרות

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

מעקב אחר עדכוני OTA

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

אחרי שמפעילים עדכון מהמסוף, כדאי לעקוב אחרי המדדים הבאים:

פירוט של תוכנות וחומרה

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

6. קבלת תמיכה

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

כניסה לערוצים למפתחים

יש שלושה ערוצים למפתחים שבהם Google עוקבת באופן פעיל:

Stack Overflow, מעקב אחר בעיות, פורום המפתחים

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

  • Stack Overflow: אתם יכולים לפנות אלינו ולקהילת המפתחים של Smart Home כדי לקבל תשובות לשאלות לגבי הטמעה או לקבל הנחיות. הערוץ הזה מתאים במיוחד לשאלות לגבי פתרון בעיות או הטמעת תכונה מסוימת.
  • מעקב אחר בעיות: זוהי המערכת הרשמית של Google למעקב אחר בעיות, שבה גורמים חיצוניים יכולים לדווח על שגיאות בסביבה העסקית. הוא מספק כלים באינטרנט לצרף קבצים ולשתף מידע רגיש במקרה הצורך. כדאי להשתמש במערכת למעקב אחר בעיות כדי לדווח על בעיות בסביבה העסקית או לשתף בקשות להוספת תכונות.
  • פורום למפתחים: כדי לקבל הנחיות מצוות התמיכה הרשמי של Google וממומחי הקהילה, אפשר לפנות אליהם דרך פורום המפתחים של Nest. הפורום הזה מתאים במיוחד לקבלת הנחיות רשמיות לפיתוח.

הרשמה לניוזלטר למפתחים

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

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

7. מזל טוב

Google Home

מעולה! למדתם איך לנפות באגים בשילובים של Matter באמצעות הכלים והשיטות שאנחנו ממליצים עליהם. אנחנו מאחלים לך עבודה נעימה ביצירת שילובים של Matter עם Google Home.

השלבים הבאים

נסו את התרגילים הבאים ועיינו במקורות מידע נוספים:

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