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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

שימוש ב-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

2. מחברים את הטלפון למחשב שבו פועל שרת ה-ADB.

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

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

$ adb devices

אמורה להתקבל תגובה שדומה לזו:

List of devices attached
<phone-id>    device

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

5. חשוב לזכור את הערך <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.

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

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

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

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

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

$ grep "MatterCommissioner" <file-name>

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

2. אם מכשיר Matter שלכם משתמש ב-Thread, תוכלו גם לחפש שגיאות שנוצרו על ידי מערכת המשנה של Thread באמצעות הפקודה הבאה:

$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

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

3. מחפשים הודעה על כשל בהקצאת הרשאות באמצעות הפקודה הבאה:

$ 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 או במכשירי מסך Nest של Google.

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

שימוש במדדים

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

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

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

בנוסף, כל בעיה בשליטה במכשיר 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: אפשר לפנות אלינו ולקהילת המפתחים של הבית החכם עם שאלות לגבי הטמעה או כדי לקבל הנחיות. הערוץ הזה הוא המקום הכי טוב לשאול איך לפתור בעיות או להטמיע תכונה מסוימת.
• Issue Tracker: זוהי המערכת הרשמית של Google למעקב אחר בעיות, שבה קהלים חיצוניים יכולים לדווח על שגיאות במערכת האקולוגית. הוא מספק כלים לאינטרנט לצירוף קבצים ולשיתוף מידע רגיש כשצריך. השימוש ב-Issue Tracker הוא הדרך הכי טובה לדווח על בעיות במערכת האקולוגית או לשתף בקשות להוספת תכונות.
• פורום למפתחים: כדי לקבל הנחיות מהתמיכה הרשמית של Google וממומחים בקהילה, אפשר לפנות לפורום למפתחים של Nest. הפורום הזה הוא המקום הטוב ביותר לקבלת הנחיות רשמיות לפיתוח.

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

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

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

7. מזל טוב

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

השלבים הבאים

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

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