אפליקציה לדוגמה
אם נתקלתם בבעיות כלשהן במהלך השימוש בממשקי ה-API של Home, אתם יכולים לאסוף יומנים כדי לבצע ניפוי באגים נוסף. כדי לאסוף יומנים מהמכשיר הנייד, צריך להשתמש ב-Android Debug Bridge (adb
). אם אתם צריכים עזרה מ-Google, עליכם לאסוף את היומנים ממכשירי Android וממרכז הבקרה, ולפתוח כרטיס במעקב הבעיות עם המידע הרלוונטי והיומנים שקשורים אליו.
איסוף יומנים של Android
כדי לבצע את כל השלבים שקשורים ל-adb
, המכשיר הנייד צריך להיות מחובר למחשב המקומי.
התקנת adb
אם עדיין לא עשיתם זאת, צריך להגדיר את Android Debug Bridge במחשב המקומי:
- מתקינים את adb במחשב.
- מפעילים את האפשרויות למפתחים ואת ניפוי הבאגים ב-USB בטלפון Android.
פלאגין Google Home ל-Android Studio
הכלי Google Home Plugin for Android Studio הוא כלי שימושי לאיסוף ולניתוח של יומנים, והוא נוצר במיוחד עבור מפתחי Google Home platform. התוסף הזה מאפשר לכם לגשת אל Google Assistant Simulator, אל Cloud Logging ואל כלים אחרים כדי לפשט את תהליך הפיתוח של smart home.
אפשר להשתמש בכלי הזה בשילוב עם adb
כדי לנתח עוד יותר את יומני המכשירים של Matter.
מידע נוסף על הכלי זמין במאמר Google Home Plugin for Android Studio.
פרטי הגרסה
מומלץ לאסוף את כל פרטי הגרסה שקשורים להגדרה בכל פעם שמחליטים לאסוף יומנים. הפעולה הזו נדרשת אם אתם צריכים לשתף בעיות עם Google.
- איך מוצאים את המזהה של המכשיר הנייד:
adb devices
List of devices attached device-id device
- אחסון הערך הזה במשתנה שנקרא
phoneid
:phoneid=device-id
- שמירת מידע שונה על המכשיר במשתנים:
containerinfo=$(adb -s $phoneid shell dumpsys package com.google.android.gms | grep "versionName" || true); homemoduleinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home " || true); optionalhomemoduleinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.optional_home " || true); policyhomemoduleinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.policy_home" || true); threadinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.threadnetwork" || true); ghainfo=$(adb -s $phoneid shell dumpsys package com.google.android.apps.chromecast.app | grep versionName || true); enabledfeatures=$((adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "Enabled features" | grep -i "home") || true); androidversion=$(adb -s $phoneid shell getprop ro.build.version.release || true); androidapiversion=$(adb -s $phoneid shell getprop ro.build.version.sdk || true)
- שמירת כל המשתנים בקובץ בשם
_versions.txt
:הרחבה להצגת פקודות לשמירת משתנים בקובץ
אפשר להעתיק את כל הבלוק ולהדביק אותו במסוף בבת אחת.
versionfile=$logtimestamp"_versions.txt" echo "Saving version info to $versionfile"
echo "Container version:" >> $versionfile echo $containerinfo >> $versionfile echo "" >> $versionfile
echo "Home Module version:" >> $versionfile echo $homemoduleinfo >> $versionfile echo "" >> $versionfile
echo "Optional Home Module version:" >> $versionfile echo $optionalhomemoduleinfo >> $versionfile echo "" >> $versionfile
echo "Policy Home Module version:" >> $versionfile echo $policyhomemoduleinfo >> $versionfile echo "" >> $versionfile
echo "Thread Module version:" >> $versionfile echo $threadinfo >> $versionfile echo "" >> $versionfile
echo "GHA version:" >> $versionfile echo $ghainfo >> $versionfile echo "" >> $versionfile
echo "Android version: " >> $versionfile echo $androidversion >> $versionfile echo "" >> $versionfile
echo "Android API version: " >> $versionfile echo $androidapiversion >> $versionfile echo "" >> $versionfile
echo "Found enabled features (blank if missing):" >> $versionfile echo $enabledfeatures >> $versionfile echo "" >> $versionfile
- בודקים את התוכן של
_versions.txt
:cat _versions.txt
עכשיו אפשר לספק את הקובץ הזה ל-Google לצורך פתרון בעיות, לפי הצורך.הרחבה להצגת פלט של קובץ לדוגמה
Container version: versionName=23.19.12 (190400-530524295) versionName=22.46.17 (190408-491726958)
Home Module version: com.google.android.gms.home [v230508900]
Optional Home Module version:
Policy Home Module version: com.google.android.gms.policy_home [230508900] [230508900065.505615668.505615668] [Download:000003be/dl-Home.integ_230508900100400.apk] [download:/Home.integ/230508900100400:Home.integ:230508900100400]
Thread Module version: com.google.android.gms.threadnetwork [v231912000]
GHA version: versionName=3.2.32.1
Android version: 13
Android API version: 33
Found enabled features (blank if missing):
איסוף יומנים
כדי לאסוף יומנים, סוגרים את כל האפליקציות שפועלות במכשיר הנייד. לאחר מכן:
- פותחים חלון טרמינל ומנקים את יומני המכשיר הקיימים:
adb logcat -b all -c
- מתחילים את תהליך איסוף היומנים:
משאירים את הטרמינל פתוח. הפעולה הזו תאסוף יומנים מהמכשיר כל עוד התהליך פועל.adb logcat >> _logs.txt
- מריצים את האפליקציה לדוגמה ומתעדים את כל הפעולות בממשק המשתמש. בסיום, עוצרים את התהליך
logcat
שפועל במסוף על ידי הקשה על Ctrl+C (או על Cmd+C ב-Mac). - היומנים מהסשן הזה נשמרים בקובץ בשם
_logs.txt
.
אפשר לנתח את המידע בקובץ הזה בדרכים שונות, כולל חיפוש מילות מפתח כמו error
, exception
או crash
.
סקריפטים של יומנים
לנוחיותכם, באפליקציית הדוגמה יש סקריפטים לקבלת היומנים הרלוונטיים, והם נאספים לקובץ טקסט. כדי לספק את חוויית ניפוי הבאגים הטובה ביותר, צריך לצרף את היומנים האלה לכל באג שמדווח כדי לאפשר ל-Google לנתח את שורש הבעיה.
היומנים האלה נמצאים בספרייה scripts
בעץ המקור של אפליקציית הדוגמה.
מבצעים את השלבים הבאים מהספרייה הבסיסית של הפרויקט:
- איך מוצאים את המזהה של המכשיר הנייד:
adb devices -l
List of devices attached device-id device
- מריצים את הסקריפט
get_logs.sh
:./scripts/get_logs.sh device-id
Cleared previous logs from device. Saving version information to home_api_sample_logs_20240605233243.txt... Saving logs to home_api_sample_logs_20240605233243.txt... (Press CTRL+C to stop the script)
- משחזרים את הבעיה.
- לוחצים על
CTRL+C
כדי להפסיק את התסריט.
הסקריפט ייצור קובץ יומן עם חותמת זמן שמכיל את כל המידע הרלוונטי. אם נתקלתם בבאגים, צרפו את הקבצים האלה לדוחות.
יומנים של מכשירי Cast Hub
אפשר להשתמש בשיטה הזו כדי לראות את יומני המכשירים של Google Nest Hub. השיטה הזו נתמכת בדגמים הבאים:
- Google Home
- Google Nest Audio
- Google Nest Hub
- Google Nest Mini
כדי להפעיל מרכז Cast לאחזור יומנים מקומיים:
- הגדרת ממשק הגישור של Android (ADB)
כדי לראות את כתובת ה-IP של הרכזת:
- במרכז הבקרה, אם יש לו מסך:
- מחליקים למטה מהחלק העליון של המסך.
- מקישים על סמל ההגדרות
- כדי למצוא את כתובת ה-IP של המכשיר: ב-Nest Hub (2nd gen), עוברים אל פרטי המכשיר > מידע טכני > כתובת IP.
- מתוך GHA בטלפון:
- מקישים על המכשיר כדי לפתוח את דף הפרטים שלו.
- מקישים על סמל ההגדרות כדי לפתוח את דף ההגדרות.
- כדי למצוא את כתובת ה-IP של המכשיר: עוברים אל פרטי המכשיר > מידע טכני > כתובת IP
- במרכז הבקרה, אם יש לו מסך:
במחשב שמחובר לאותה רשת Wi-Fi שאליה מחובר המכשיר:
adb connect ip-address
adb logcat
כדי לספק יומנים למישהו, מבצעים את הפעולה שנכשלה ומעבירים את הפלט לקובץ טקסט:
adb logcat -d > platform-logs.txt
פעולות אוטומטיות
זיהוי קצוות
האוטומציות במערכת האקולוגית של Google Home כוללות זיהוי קצה, שהוא לוגיקה שמוודאת שהפעלה מתרחשת רק כשחל שינוי בפועל במצב, ולא כשמתבצע עדכון מצב שפשוט חוזר על המצב הקודם של המכשיר.
לדוגמה, אם הדלקת אור היא פעולת התנעה, זיהוי קצה מוודא שפעולת ההתנעה מופעלת רק אם מכשיר התאורה עובר ממצב כבוי למצב דלוק, ולא ממצב דלוק למצב דלוק (ללא שינוי).
האוטומציה לא מתנהגת כצפוי
אחרי שמתחשבים בזיהוי הקצוות, אם אוטומציה לא מתנהגת כמצופה:
בודקים כל מכשיר כדי לוודא שהוא פועל בצורה תקינה ללא קשר לאוטומציה.
כדאי לעיין בתרשים האוטומציה של האוטומציה שלכם, ולהשוות אותו ל-DSL של האוטומציה, כדי לגלות הנחות שגויות פוטנציאליות מצדכם.
אפשר לעקוב אחרי מצב המכשיר באפליקציית Google Home במהלך ההפעלה של האוטומציה.
בודקים שכל המכשירים שהאוטומציה מתייחסת אליהם נמצאים במבנה שבו אתם מצפים שהם יהיו. למחיקה של מכשיר שפעולה אוטומטית מסתמכת עליו יכולות להיות השלכות לא רצויות. השפעת מחיקת מכשיר על אוטומציות
הפעולה האוטומטית מופעלת שלא לצורך
אם האוטומציה פועלת כשהיא לא אמורה לפעול, צריך לבדוק את קריטריוני ההתחלה. יכול להיות שיהיה צורך להוסיף לוגיקה נוספת כדי לוודא ששינוי במצב מתועד רק פעם אחת ומפעיל את האוטומציה רק פעם אחת.
האוטומציה לא עוברת קומפילציה
חשוב לוודא שהאפליקציה מכילה את כל הייבוא הנדרש, כולל כל מחלקה שמתאימה לסוגי הצמתים השונים, וגם את התכונות שאתם מפנים אליהן.
יצירת אוטומציה נכשלת באימות
אם יצירת האוטומציה לא עוברת את האימות, תוצג הודעת אזהרה או הודעת שגיאה עם מידע על הבעיה. מידע נוסף זמין במאמר הזה.ValidationIssueType
הפונקציה List מחזירה חריגים
כשקוראים לפונקציית הרשימה של Automation API, יכול להיות שמטפלי קריאה יזרקו חריגים בגלל תכונות API חסרות. כדי לפתור את הבעיה, מוחקים את האוטומציה המושפעת.
לשם כך:
- בודקים ש
adb
installed מותקן. איך מתקינים adb כדי לאחזר את המזהה של האוטומציה מיומני Android, מפעילים את הפקודה:
adb logcat -s GhpNative
יומנים לדוגמה:
adb logcat -s GhpNative level:debug | grep -A 10 -B 10 AutomationManagerTrait\.ListResponse INTERACTION RESPONSE -> SendCommandsResponse: 1 { 1: "automation@global" 3 { 1: "home.internal.traits.automation.AutomationManagerTrait.ListResponse" 2: 5 { 1: "type.googleapis.com/home.internal.traits.automation.AutomationManagerTrait.ListResponse" 1 { 1: "1111-2222-3333-44444-55555" // Automation ID to delete 2: "structure@2222-3333-4444-5555-6666" ...
אם צריך למחוק כמה מזהי אוטומציה, אפשר להשתמש בכלי להצגת פלט בטרמינל כדי לשלוט בפלט:
adb logcat -s GhpNative level:debug | less
מחיקת הפעולה האוטומטית באמצעות המזהה שלה:
structure.deleteAutomation(new object : HasId(id = "1111-2222-3333-44444-55555"))
Discovery API מתעד אזהרה כשמאפיין לא רשום
אם ה-API של Discovery מתעד אזהרה לגבי Trait not found
, המשמעות היא שה-API מנסה להשתמש בתכונה למועמדים ל-Discovery, אבל הוא לא יצליח כי התכונה לא נרשמה במהלך האתחול. לדוגמה:
09-03 17:45:20.578 10646 10646 W AutomationSdk: trait_id: "home.matter.6006.clusters.fc43" and Exception occurred com.google.home.HomeException: 18: Trait not found: home.matter.6006.clusters.fc43
09-03 17:45:20.578 10646 10646 W AutomationSdk: While converting candidate: # com.google.home.platform.traits.AutomationCandidateNode@76f0b582
מזהה המאפיין הוא home.matter.6006.clusters.fc43
, שמתאים ל-RelativeHumidityControl
. כדי לדעת מהו שם המאפיין לפי מזהה, אפשר לעיין באינדקס המאפיינים.
בדוגמה הזו, צריך לרשום את RelativeHumidityControl
במהלך האתחול של האפליקציה. כדי להוסיף את המאפיין למרשם, אפשר להיעזר במאמר בנושא רישום מאפיינים.
OAuth
אם יש לכם לקוח OAuth קיים
אם כבר יש לכם לקוח OAuth מאומת לאפליקציה שפורסמה, אתם יכולים להשתמש בלקוח ה-OAuth הקיים כדי לבדוק את ממשקי ה-API של Home.
אין צורך ברישום Google Home Developer Console כדי לבדוק את ממשקי ה-API של Home ולהשתמש בהם. עם זאת, עדיין תצטרכו רישום מאושר של Developer Console כדי לפרסם את האפליקציה, גם אם יש לכם לקוח OAuth מאומת משילוב אחר.
צריך להתחשב בשיקולים הבאים:
קיימת מגבלה של 100 משתמשים כשמשתמשים בלקוח OAuth קיים. מידע על הוספת משתמשים למטרות בדיקה זמין במאמר בנושאהגדרת מסך ההסכמה של OAuth. בנוסף לאימות OAuth, יש מגבלה של 100 משתמשים שיכולים להעניק הרשאות לאפליקציה שלכם, שמוגדרת על ידי Home APIs. המגבלה הזו תוסר לאחר השלמת הרישום של Developer Console.
Developer Console registration צריך לשלוח לאישור כשמוכנים להגביל הרשאות לפי סוג המכשיר באמצעות OAuth, כהכנה לעדכון האפליקציה באמצעות ממשקי ה-API של Home.
באפליקציות Google Cloud שעדיין בהמתנה לאימות OAuth, המשתמשים לא יכולים להשלים את תהליך OAuth עד שהאימות יושלם. ניסיונות להעניק הרשאות ייכשלו עם השגיאה הבאה:
Access blocked: <Project Name> has not completed the Google verification process.