פתרון בעיות

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

אם נתקלתם בבעיות כלשהן במהלך השימוש בממשקי ה-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. מריצים את האפליקציה לדוגמה ומתעדים את כל הפעולות בממשק המשתמש. בסיום, עוצרים את התהליך logcat שפועל במסוף על ידי הקשה על Ctrl+C (או על Cmd+C ב-Mac).
  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 Hub

אפשר להשתמש בשיטה הזו כדי לראות את יומני המכשירים של Google Nest Hub. השיטה הזו נתמכת בדגמים הבאים:

  • Google Home
  • Google Nest Audio
  • Google Nest Hub
  • Google Nest Mini

כדי להפעיל מרכז Cast לאחזור יומנים מקומיים:

  1. הגדרת ממשק הגישור של Android‏ (ADB)
  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 installed מותקן. איך מתקינים 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"
    ...

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

    adb logcat -s GhpNative level:debug | less
  3. מחיקת הפעולה האוטומטית באמצעות המזהה שלה:

    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.