1. לפני שמתחילים
Matter מציע למשתמשים חוויית הגדרה ושליטה חלקה במכשירים בפלטפורמות שונות. הסיבה העיקרית לכך היא הרכיבים השונים של הסביבה העסקית שפועלים יחד מאחורי הקלעים. לפעמים פיתרון בעיות במערכות כאלה יכול להיות מרתיע למפתחים חדשים, לכן פיתחנו סדרה של כלים ושיטות שיעזרו לכם לפתור בעיות בקלות רבה יותר כמפתחים של Matter עם Google Home.
בקודלאב הזה נסביר על שלושה רכיבים עיקריים של Matter. לכל אחת מהמערכות האלה, Google מספקת למפתחים ניתוח נתונים לפתרון בעיות שנאסף מטלפונים ומרכזיות:
כמפתחים, חשוב מאוד שתוכלו לצמצם את הבעיות שאתם נתקלים בהן במהלך מחזור הפיתוח של המכשיר. אחרי השקת הפרויקט, צריך לעקוב באופן מצטבר אחרי מגמות בבעיות במכשירים בשטח ולפתור אותן באמצעות עדכוני תוכנה. בקודלאב הזה נסביר על טכניקות שאפשר להשתמש בהן לשתי המטרות האלה.
דרישות מוקדמות
- השלמת המדריך תחילת העבודה עם 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 יש קבוצה של תרשימים שמאפשרים לעקוב אחרי הצלחת ההפעלה, וגם אחרי השקות של עדכונים במכשירים.
חשוב לזכור שתצוגת ברירת המחדל עם התרשימים שמוצגים במרכזי הבקרה של Google Home Analytics היא רק תצוגה שיצרנו לפרויקט שלכם באמצעות נתוני מדדי הבית החכם. אפשר גם להשתמש ב-Metrics Explorer כדי ליצור תרשימים משלכם מאותו בסיס של מדדים ולשמור אותם במרכזי הבקרה המותאמים אישית.
גישה ליומני השגיאות
Logs Explorer הוא אוסף כלים לעבודה עם יומני אירועים שנוצרו בפרויקט. אפשר לגשת אליו במסוף Google Cloud, דרך Operations > Logging > Logs Explorer.
כשפותחים את Logs Explorer, מופיעה תצוגה שנראית כך:
חלון הניווט מכיל כלים שונים להצגה, לסינון, לשאילתות ולניתוח של יומנים. כברירת מחדל, בתצוגה הזו מוצגים יומנים שנוצרו מכל המערכות הזמינות לפרויקט, כולל יומנים שנוצרו מחוץ ל-Smart Home. לכן חשוב להשתמש ביומני האלה על ידי סינון של האירועים שרוצים לנפות באגים בהם. נרחיב על כך בקטעים של ניפוי הבאגים.
3. ניפוי באגים בבעיות שקשורות להפעלה
הסוג הראשון של המדדים שנבחן הוא אירועי הזמנת Matter. ההגדרה מתייחסת לקבוצת השלבים שצריך לבצע כדי שמשתמש יוכל להגדיר מכשיר Matter בפעם הראשונה.
במהלך ההפעלה של המכשיר מתבצעות אינטראקציות בין מכשיר Matter, אפליקציית Google Home ו-Matter Fabric. בתמונה הבאה מוצגים חלק מהאירועים האלה:
מידע נוסף על כל אחד מהשלבים האלה זמין בדף ההזמנה במדריך 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 Debug Bridge (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 תהיה גישה ליומנים שנוצרו על ידי אפליקציות שפועלות כרגע במכשיר.
אחזור מזהה המכשיר
- מריצים את שרת ה-ADB באמצעות הפקודה הבאה:
$ adb start-server
- מחברים את הטלפון למחשב שבו פועל שרת ה-ADB.
יכול להיות שתופיע בטלפון הודעת אזהרה לגבי ניפוי באגים ב-USB, עם שאלה אם רוצים לאפשר למחשב לגשת למידע מהטלפון:
- אם מופיעה הודעת האזהרה הזו, לוחצים על אישור.
- נותנים את הפקודה list devices בטרמינל כדי לבדוק אם למחשב יש גישה לטלפון דרך ADB. כדי לעשות זאת, מזינים את הפקודה הבאה:
$ adb devices
התגובה אמורה להיראות כך:
List of devices attached <phone-id> device
הערך של <phone-id> הוא מחרוזת אלפאנומרית שמזהה את המכשיר באופן ייחודי.
- חשוב לזכור את הערך של
<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"
חשוב לוודא שהסביבה העסקית שלנו תומכת בערכים האלה. כשאתם פונים לתמיכה לגבי כשלים בהפעלה, חשוב תמיד לכלול את פרטי המערכת בכרטיסי התמיכה.
איסוף יומני שגיאות
לאחר מכן, מתחילים את תהליך איסוף היומנים ומבצעים את שלבי ההפעלה כדי ליצור את אירועי השגיאה שרוצים לנפות באגים מהם.
- מריצים את הפקודה הבאה ומספקים את
<phone-id>ואת<file-name>שבו היומנים יישמרו במחשב (למשל,debug_file.txt).
$ adb -s <phone-id> logcat > <file-name>
הפעולה הזו תפעיל מיד את תהליך הרישום ביומן. אם קובץ בשם הזה לא קיים, הוא נוצר, ויומנים מהטלפון מתווספים לקובץ אחרי כל אירוע.
ממשיכים בשלבים להפעלה של מכשיר Matter.
- כשמגיעים לשגיאה שרוצים לנפות באגים, לוחצים על
Control+Cבחלון מסוף הפעלה כדי להפסיק את הרישום ביומן.
היומנים אמורים להישמר עכשיו בקובץ הרישום <file-name>. מאחר שהתהליך הזה מתעד יומנים מכל תהליך פעיל במכשיר שאנחנו עוקבים אחריו, יהיו הרבה יומנים בקובץ הזה. לכן, תמיד כדאי לחפש את הרשומות הנחוצות ביומני האלה.
ניתוח יומני השגיאות
תהליכי ההפעלה מטופלים באמצעות מערכת משנה שנקראת MatterCommissioner ב-GHA.
- בהתאם לאסטרטגיה הראשית שמשמשת לניתוח שגיאות בהפעלה, מחפשים שגיאות שנוצרו על ידי מערכת המשנה MatterCommissioner באמצעות הפקודה הבאה:
$ grep "MatterCommissioner" <file-name>
הפלט שנוצר מכיל את האירועים מתהליך ההזמנה.
- אם מכשיר Matter משתמש ב-Thread, אפשר גם לחפש שגיאות שנוצרו על ידי מערכת המשנה של Thread באמצעות הפקודה הבאה:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>
בזמן הניתוח של קובץ היומן שנוצר בתהליך ניפוי הבאגים ב-ADB, כדאי לחפש גם דפוסים מסוימים. הרבה שגיאות בהפעלה כוללות את המחרוזת commissioning failure בהודעת השגיאה.
- מחפשים הודעה על כשל בהפעלה באמצעות הפקודה הבאה:
$ 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: אתם יכולים לפנות אלינו ולקהילת המפתחים של Smart Home כדי לקבל תשובות לשאלות לגבי הטמעה או לקבל הנחיות. הערוץ הזה מתאים במיוחד לשאלות לגבי פתרון בעיות או הטמעת תכונה מסוימת.
- מעקב אחר בעיות: זוהי המערכת הרשמית של Google למעקב אחר בעיות, שבה גורמים חיצוניים יכולים לדווח על שגיאות בסביבה העסקית. הוא מספק כלים באינטרנט לצרף קבצים ולשתף מידע רגיש במקרה הצורך. כדאי להשתמש במערכת למעקב אחר בעיות כדי לדווח על בעיות בסביבה העסקית או לשתף בקשות להוספת תכונות.
- פורום למפתחים: כדי לקבל הנחיות מהתמיכה הרשמית של Google וממומחי הקהילה, אפשר לפנות אליהם דרך פורום המפתחים של Nest. הפורום הזה מתאים במיוחד לקבלת הנחיות רשמיות לפיתוח.
הרשמה לניוזלטר למפתחים
בנוסף לשאלות שאפשר לפרסם בערוצי המפתחים, אנחנו גם מפרסמים ניוזלטר רבעוני שבו מודגשות תכונות חדשות ומפורטים עדכונים על המצב בסביבה העסקית של הבית החכם של Google.
אתם יכולים להשתמש בטופס ההרשמה כדי לקבל את ניוזלטר המפתחים.
7. מזל טוב
מעולה! למדתם איך לנפות באגים בשילובים של Matter באמצעות הכלים והשיטות שאנחנו ממליצים עליהם. אנחנו מאחלים לך עבודה נעימה ביצירת שילובים של Matter עם Google Home.
השלבים הבאים
כדאי לנסות את התרגילים הבאים ולעיין במקורות מידע נוספים:
- בנוסף לניתוח נתונים כדי לפתור בעיות, אפשר גם להשתמש בחבילת בדיקות כדי לבדוק את השילוב ולזהות בעיות פוטנציאליות.
- כשהשילוב מוכן לשיתוף עם העולם, השלב הבא הוא לקבל לפרויקט אישור WWGH. כדי לעשות זאת, פועלים לפי השלבים שמפורטים בדף אישור.