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

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

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

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

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

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

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

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

מה תלמדו

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

2. הצגת Analytics של Google Home

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

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

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

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

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

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

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

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

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

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

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

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

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

סייר היומנים

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

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

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

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

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

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

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

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

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

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

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

6. בקשת תמיכה

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

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

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

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

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

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

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

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

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

7. מזל טוב

Google Home

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

השלבים הבאים

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

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