פתרון בעיות

אפליקציה לדוגמה

אם תיתקלו בבעיות במהלך השימוש בממשקי ה-API של Home, תוכלו לאסוף יומנים לצורך ניפוי באגים נוסף. כדי לאסוף יומנים מהמכשיר הנייד, צריך להשתמש ב-Android Debug Bridge‏ (adb). אם אתם זקוקים לעזרה מ-Google, עליכם לאסוף את היומנים גם ממכשירי Android וגם מהרכז, ולפתוח כרטיס במערכת למעקב אחר בעיות עם המידע הרלוונטי והיומנים המשויכים.

איסוף יומני Android

המכשיר הנייד צריך להיות מחובר למחשב המקומי בכל השלבים שכוללים את adb.

התקנת adb

אם עדיין לא עשיתם זאת, מגדירים את Android Debug Bridge במחשב המקומי:

  1. מתקינים את 'adb' במחשב.
  2. מפעילים את האפשרויות למפתחים ואת ניפוי הבאגים ב-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.

  1. קבלת המזהה של המכשיר הנייד: 
    adb devices
     
    List of devices attached
device-id    device
  2. שומרים את הערך הזה במשתנה שנקרא phoneid: 
    phoneid=device-id
  3. שמירת פרטים שונים של המכשיר במשתנים: 
    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)
  4. שומרים את כל המשתנים בקובץ בשם _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
  5. מאמתים את התוכן של _versions.txt: 
    cat _versions.txt

    הרחבה להצגת פלט של קובץ לדוגמה

    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):
    עכשיו אפשר לספק את הקובץ הזה ל-Google לפי הצורך לצורך פתרון בעיות.

איסוף יומנים

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

  1. פותחים חלון טרמינל ומוחקים את יומני המכשיר הקיימים: 
    adb logcat -b all -c
  2. מתחילים בתהליך איסוף היומנים: 
    adb logcat >> _logs.txt
     משאירים את הטרמינל הזה פתוח. כך יוכלו להצטבר יומנים מהמכשיר כל עוד התהליך פועל.
  3. מריצים את האפליקציה לדוגמה ומתעדים את כל הפעולות בממשק המשתמש. בסיום, מקישים על Ctrl+C (או על Cmd+C ב-Mac) כדי לעצור את תהליך logcat שפועל במסוף.
  4. היומנים מהסשן הזה נשמרים בקובץ בשם _logs.txt.

אפשר לנתח את המידע בקובץ הזה בדרכים שונות, כולל חיפוש של מילות מפתח כמו error, ‏exception או crash.

סקריפטים ביומן

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

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

  1. קבלת המזהה של המכשיר הנייד: 
    adb devices -l
     
    List of devices attached
device-id device
  2. מריצים את הסקריפט 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)
  3. משחזרים את הבעיה.
  4. כדי להפסיק את הסקריפט, מקישים על CTRL+C.

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

יומני המכשיר של מרכז ה-Cast

כדי להציג את יומני המכשיר של Google Hub:

  1. הגדרת Android Debug Bridge

  2. מוצאים את כתובת ה-IP של הצומת:

    • במרכז הבקרה, אם יש לו מסך:
      1. מחליקים למטה מהחלק העליון של המסך.
      2. מקישים על סמל ההגדרות .
      3. מחפשים את כתובת ה-IP של המכשיר: ב-Nest Hub (2nd gen), עוברים אל פרטי המכשיר > מידע טכני > כתובת IP.
    • מ-GHA בטלפון:
      1. מקישים על המכשיר כדי להציג את דף הפרטים שלו.
      2. מקישים על סמל ההגדרות כדי להציג את דף ההגדרות.
      3. מוצאים את כתובת ה-IP של המכשיר: עוברים אל פרטי המכשיר > מידע טכני > כתובת IP.

  3. במחשב שמחובר לאותה רשת Wi-Fi כמו המכשיר: 

      adb connect ip-address
  adb logcat

  4. כדי לספק יומנים למישהו, מבצעים את הפעולה שנכשלת ומעבירים את הפלט לצינור לקובץ טקסט: 

      adb logcat -d > platform-logs.txt

פעולות אוטומטיות

זיהוי קצוות

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

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

הפעולה האוטומטית לא פועלת כצפוי

אחרי שמביאים בחשבון את זיהוי הקצוות, אם תהליך אוטומציה לא פועל כצפוי:

  1. בודקים כל מכשיר כדי לוודא שהוא פועל כמו שצריך, ללא קשר לתהליך האוטומציה.

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

  3. במהלך ביצוע הפעולה האוטומטית, אפשר לראות את מצב המכשיר באפליקציית Google Home.

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

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

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

המערכת האוטומטית לא מקמפל

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

יצירת האוטומציה נכשלת בתיקוף

אם תהליך היצירה של האוטומציה לא עובר אימות, תוצג הודעת אזהרה או שגיאה עם מידע על הבעיה. למידע נוסף, עיינו במקור המידע ValidationIssueType.

פונקציית הרשימה גורמת להשלכות

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

לשם כך:

  1. מוודאים ש-adb מותקן. התקנת adb

  2. כדי לאחזר את המזהה של האוטומציה מהיומנים של 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"
...

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

    adb logcat -s GhpNative level:debug | less

  3. מוחקים את הפעולה האוטומטית באמצעות המזהה שלה:

    structure.deleteAutomation(new object : HasId(id = "1111-2222-3333-44444-55555"))

כשמאפיין לא רשום, נרשמת ביומן של Discovery API אזהרה

אם ביומן של Discovery API מופיעה אזהרה לגבי 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 הקיים כדי לבדוק את Home APIs.

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

יש להביא בחשבון את השיקולים הבאים:

  • כשמשתמשים בלקוח OAuth קיים, יש מגבלה של 100 משתמשים. מידע נוסף על הוספת משתמשים לצורך בדיקה זמין במאמר הגדרת מסך ההסכמה ל-OAuth. ללא קשר לאימות OAuth, יש מגבלה של 100 משתמשים שיכולים להעניק הרשאות לאפליקציה שלכם, והיא מוגדרת על ידי ממשקי ה-API של Home. ההגבלה הזו תוסר לאחר השלמת הרישום ב-Developer Console.

  • Developer Console רישום צריך לשלוח לאישור כשאתם מוכנים להגביל את ההרשאות לפי סוג המכשיר באמצעות OAuth, לקראת עדכון האפליקציה באמצעות ממשקי ה-API של Home.

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

Access blocked: <Project Name> has not completed the Google verification process.
הקודם
ממשק API של אתחול והרשאות
הבא
ממשק API של עמלה