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

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

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

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

    Если необходимо удалить несколько идентификаторов автоматизации, вы можете использовать пейджер терминала для управления выводом: 

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

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

Принимаются во внимание следующие факторы:

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

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

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

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