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

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

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

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

הזמנה, ביצוע, עדכון OTA

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

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

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

מה תלמדו

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

2. הצגת ניתוח הנתונים בדף הבית של Google

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

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

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

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

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

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

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

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

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

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

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

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

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

סייר היומנים

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

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

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

במהלך הזמנת המכשיר, מתקיימת קבוצת אינטראקציות בין מכשיר בתקן Matter, אפליקציית Google Home והמארג של 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, מריצים מהמסוף פקודה של רשימת מכשירים כדי לבדוק אם:
$ adb devices

הפעולה הזו אמורה לספק תשובה שדומה לזו:

List of devices attached
<phone-id>    device

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

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

איסוף נתוני המערכת

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

  • כך בודקים את הגרסה של Android OS:
$ 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"
  • כדי לבדוק אם יש לכם את המודולים של בקרת הבית / 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 באמצעות הפקודה הבאה:
$ 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.

מאחר שמפרט הבקרה בין מכשירי קצה לבין מכשירי Google Hub מתווכים על ידי 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 (OTA) למכשירי Matter בהנפקת Google Home, אנחנו מספקים קבוצת מדדים שמראים את גרסאות החומרה והתוכנה של המכשירים בשטח.

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

תקלות בתוכנה ובחומרה

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

6. פנייה לתמיכה

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

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

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

גלישת מחסנית, מעקב אחר בעיות, פורום למפתחים

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

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

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

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

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

7. מזל טוב

Google Home

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

השלבים הבאים

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

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