Устранение неполадок

Пример приложения

Если у вас возникнут проблемы при использовании Home API, вы можете собрать логи для дальнейшей отладки. Для сбора журналов с мобильного устройства требуется 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 , облачному журналированию и другим инструментам, упрощающим процесс разработки 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 .

Лог-скрипты

Для вашего удобства приложение Sample App предоставляет скрипты для получения соответствующих журналов и компиляции их в текстовый файл. Для обеспечения наилучшего процесса отладки эти журналы следует прикреплять к любым сообщениям об ошибках, чтобы 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 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 .

Функция списка выдает исключения

При вызове функции списка 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"))

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.

Для тестирования и использования Home API регистрация Google Home Developer Console не требуется. Однако для публикации приложения вам всё равно потребуется подтверждённая регистрация Developer Console , даже если у вас есть проверенный OAuth-клиент из другой интеграции.

При этом следует учитывать следующие соображения:

  • При использовании существующего клиента OAuth существует ограничение в 100 пользователей. Подробнее о добавлении тестовых пользователей см.Настройте экран согласия OAuth .Независимо от проверки OAuth, Home APIs устанавливает ограничение в 100 пользователей, которые могут предоставить разрешения вашему приложению. Это ограничение снимается после регистрации в Developer Console .

  • Регистрация Developer Console следует отправить на утверждение, когда вы будете готовы ограничить предоставление разрешений на тип устройства через OAuth в рамках подготовки к обновлению вашего приложения с помощью API Home.

Для приложений Google Cloud , которые всё ещё ожидают проверки OAuth, пользователи не смогут завершить процесс OAuth до завершения проверки. Попытки предоставить разрешения завершатся со следующей ошибкой: 

Access blocked: <Project Name> has not completed the Google verification process.