Отладка интеграций Matter

1. Подготовка

Matter обеспечивает конечным пользователям удобную межплатформенную настройку устройств и управление ими. Это возможно благодаря тому, что за кулисами работают несколько компонентов экосистемы, которые взаимодействуют друг с другом. Устранение неполадок в таких системах часто пугает начинающих разработчиков, поэтому мы создали ряд инструментов и методов, которые упростят вашу жизнь как разработчика Matter с Google Home.

В этой практической работе рассматриваются три основных компонента Matter. Для каждой из этих систем Google предоставляет разработчикам набор аналитических данных для устранения неполадок, собранных с телефонов и хабов:

Инициализация, выполнение, беспроводное обновление

Разработчикам важно уметь устранять проблемы, возникающие на протяжении всего цикла разработки устройства. После запуска проекта вам нужно будет отслеживать тенденции в отношении проблем с устройствами, находящимися в эксплуатации, и устранять их с помощью обновлений ПО. В этой практической работе мы расскажем, как это сделать.

Требования

  • Выполните инструкции из руководства Начало работы с Matter, чтобы создать рабочий проект Matter и настроить устройство.
  • Телефон Android, который можно подключить к рабочей станции (для журналов ADB).

Что вы узнаете

  • Как использовать инструменты аналитики для умного дома, чтобы отслеживать проблемы с Matter в больших масштабах.
  • Как сортировать ошибки, используя журналы ошибок и собирая информацию.
  • Как найти документацию и ресурсы поддержки Matter.

2. Как посмотреть статистику Google Home

Мониторинг производительности имеет решающее значение для успешной интеграции с экосистемой Google Home. Разработчикам умного дома мы предоставляем набор инструментов мониторинга на платформе Google Cloud. Вы можете использовать эти инструменты для оценки эффективности вашего проекта.

Как посмотреть показатели проекта

  • Чтобы получить доступ к данным, сначала проверьте панели Google Home. Для этого войдите в Google Cloud Console и выберите Operations (Операции) > Monitoring (Мониторинг) > Dashboards (Панели).

Для вашего проекта доступно несколько панелей управления (в том числе для других продуктов Google Cloud). Сводки для умного дома имеют префикс Google Home Analytics.

Панели аналитики Google Home

Сейчас у нас есть общая панель управления, которая охватывает весь проект, а также панели управления для конкретных интеграций (Cloud, Local, Matter) или типов устройств (камеры). Данные на этих панелях будут доступны, только если у вас есть интеграция соответствующего типа и работающий проект, выполняющий запросы.

Открыв одну из этих панелей, вы увидите несколько диаграмм, похожих на следующие:

Доля успешных транзакций, задержка и распределение по типам устройств

На панелях Google Home есть различные диаграммы с подробными сведениями о событиях, связанных с вашим проектом. На панели управления каждой интеграции вы увидите диаграмму с общим количеством запросов, обработанных вашим проектом, диаграмму с долей успешных запросов для этого типа интеграции и несколько диаграмм с типами и характеристиками устройств. Кроме того, для устройств Matter доступны диаграммы, на которых показаны успешные вводы в эксплуатацию и развертывания обновлений.

Обратите внимание, что представление по умолчанию с диаграммами, которые вы видите на панелях мониторинга Google Home Analytics, – это просто представление, которое мы создали для вашего проекта с использованием данных показателей умного дома. Вы также можете использовать Metrics Explorer, чтобы создавать собственные диаграммы на основе тех же показателей и сохранять их в сводках.

Как получить доступ к журналам ошибок

Logs Explorer – это набор инструментов для работы с журналами событий, созданными в проекте. Чтобы открыть его, в консоли Google Cloud выберите Operations (Операции) > Logging (Ведение журналов) > Logs Explorer (Просмотр журналов).

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

Конструктор запросов и результаты поиска в Logs Explorer

В окне проводника есть различные инструменты для просмотра, фильтрации, запроса и анализа журналов. По умолчанию в этом представлении показаны журналы, созданные всеми системами, доступными для вашего проекта, включая журналы, созданные за пределами умного дома. Поэтому важно фильтровать события, которые вы хотите отладить. Подробнее об этом мы поговорим в разделах, посвященных отладке.

3. Устранение неполадок при вводе в эксплуатацию

Первый тип показателей, который мы рассмотрим, относится к событиям ввода в эксплуатацию Matter. Ввод в эксплуатацию – это набор действий, которые пользователь должен выполнить, чтобы настроить устройство Matter в первый раз.

Во время ввода в эксплуатацию устройство Matter, приложение Google Home и сеть Matter взаимодействуют друг с другом. На изображении ниже показаны некоторые из этих событий.

Последовательность событий при вводе устройства Matter в эксплуатацию между устройством, приложением Google Home и сетью Matter

Подробную информацию о каждом из этих шагов можно найти на странице, посвященной вводу в эксплуатацию, в руководстве по Matter. В этом разделе мы рассмотрим инструменты и методы отладки проблем с вводом в эксплуатацию.

Как использовать Google Home Analytics

Мы создали набор показателей, которые помогут вам выявлять проблемы с вводом в эксплуатацию, отслеживая события и определяя, на каком этапе могут возникать ошибки. Их можно найти на панели интеграции Matter, как описано в предыдущем разделе.

На этой панели управления представлены диаграммы с данными о вводе устройств в эксплуатацию:

Диаграммы с количеством вводов устройств в эксплуатацию, долей успешных вводов и разбивкой ошибок

На диаграмме с количеством устройств показано, сколько попыток ввода в эксплуатацию было предпринято пользователями в определенный день. Доля успешных запросов показывает, сколько событий было успешно обработано Google. Каждая попытка ввода в эксплуатацию генерирует набор событий со связанными состояниями. Если на любом из этих этапов возникает ошибка, она также регистрируется на диаграмме ошибок.

Штаты, в которых взимается комиссия:

  • COMMISSIONING_STARTED
  • ONBOARDING_PAYLOAD_GENERATED
  • LOCAL_DISCOVERY_SUCCESSFUL
  • PASE_CONNECTION_SUCCESSFUL
  • NOC_ADDED_SUCCESSFULLY
  • COMMISSIONING_COMPLETE

Чтобы посмотреть подробную информацию об этих событиях, выберите Operations (Операции) > Logging (Ведение журнала) > Logs Explorer (Просмотр журналов). Чтобы отфильтровать ошибки ввода в эксплуатацию, в поле запроса можно выполнить поиск по запросу "clientUpdateLog" в сочетании с "severity>=ERROR".

Журнал ошибок ввода в эксплуатацию для Matter выглядит следующим образом:

{
  "insertId": "1a32ry0f6xpzzn",
  "jsonPayload": {
    "clientUpdateLog": {
      "MatterUpdate": {
        "reportedProductId": 55,
        "sessionId": "1584879052892229997",
        "reportedVendorId": 4800,
        "commissioningState": "GENERIC_COMMISSIONING_ERROR",
        "status": "GENERIC_ERROR"
      }
    }
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "<project-id>"
    }
  },
  "timestamp": "2023-03-01T07:09:55.216425297Z",
  "severity": "ERROR",
  "logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2023-03-01T07:09:55.216425297Z"
}

Помимо состояния ввода в эксплуатацию и кода статуса, журнал ошибок содержит временные метки для зарегистрированной ошибки, а также идентификатор товара Matter, который позволяет определить, какой из ваших товаров вызвал ошибку. У набора журналов, созданных в рамках одной попытки ввода в эксплуатацию, будет одинаковый sessionId.

Показатели Google Home Analytics позволяют понять, на каком этапе может возникать проблема. Чтобы найти основную причину ошибок при вводе устройства в эксплуатацию, иногда может потребоваться выполнить дополнительную отладку с помощью журналов, созданных мобильным устройством, которое использовалось в процессе ввода в эксплуатацию. Для этого вам понадобится Android Debug Bridge.

Как использовать Android Debug Bridge (ADB)

Ещё один способ устранить неполадки с вводом в эксплуатацию – использовать инструмент командной строки Android Debug Bridge (ADB). Поскольку ввод в эксплуатацию в основном выполняется между мобильным устройством и устройством Matter, вы можете использовать инструмент ADB для доступа к журналам, созданным приложением Google Home во время ввода в эксплуатацию.

Установите инструменты платформы

ADB входит в состав Android SDK Platform Tools, который можно установить с помощью Android Studio или инструмента командной строки sdkmanager.

После установки инструментов платформы проверьте ADB, посмотрев номер версии в терминале с помощью следующей команды:

$ adb -- version

Должен отобразиться номер версии установленной утилиты ADB без ошибок.

Включить отладку по USB

Затем включите отладку по USB на устройстве Android.

Сначала включите режим «Для разработчиков» на устройстве, а затем включите отладку по USB.

Это позволяет ADB получать доступ к журналам, созданным приложениями, которые в данный момент запущены на устройстве.

Как получить идентификатор устройства

  1. Запустите сервер ADB с помощью следующей команды:
$ adb start-server
  1. Подключите телефон к компьютеру, на котором запущен сервер ADB.

На телефоне может появиться предупреждение об отладке по USB с вопросом, хотите ли вы разрешить компьютеру доступ к информации на телефоне.

Диалоговое окно с запросом на разрешение отладки по USB на телефоне Android

  1. Если вы видите такое предупреждение, нажмите Разрешить.
  2. Чтобы проверить, может ли компьютер получить доступ к телефону через ADB, введите в терминале следующую команду:
$ adb devices

Вы должны получить ответ, похожий на следующий:

List of devices attached
<phone-id>    device

<phone-id> – это буквенно-цифровой идентификатор, который уникальным образом определяет ваше устройство.

  1. Запомните значение <phone-id>, чтобы использовать его на следующих шагах.

Сбор сведений о системе

Теперь проверьте информацию о версии приложений и системы на вашем устройстве.

  • Чтобы узнать версию ОС Android:
$ adb -s <phone-id> shell getprop ro.build.version.release
  • Чтобы проверить версию приложения Google Home:
$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName
  • Чтобы проверить версию сервисов Google Play:
$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"
  • Чтобы проверить, есть ли у вас модули управления Google Home или Matter, которые работают через сервисы Google Play, сделайте следующее:
$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"

Убедитесь, что эти возвращаемые значения поддерживаются нашей экосистемой. При обращении в службу поддержки по поводу сбоев ввода в эксплуатацию всегда включайте информацию о системе в свои запросы в службу поддержки.

Сбор журналов ошибок

Затем запустите процесс сбора журналов и выполните шаги по вводу в эксплуатацию, чтобы сгенерировать события ошибок, которые вы хотите отладить.

  1. Выполните следующую команду, указав <phone-id> и <file-name>, в котором будут сохранены журналы на вашем компьютере (например, debug_file.txt).
$ adb -s <phone-id> logcat > <file-name>

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

Выполните шаги по вводу в эксплуатацию устройства Matter.

  1. Когда вы дойдете до ошибки, которую хотите отладить, остановите ведение журнала, нажав Control+C в окне терминала.

Теперь журналы должны храниться в файле журнала <file-name>. Поскольку в этом файле регистрируются журналы всех запущенных процессов, отслеживаемых на устройстве, их будет много. Поэтому всегда используйте эти журналы, выполняя поиск нужных записей.

Анализ журналов ошибок

Процессы ввода в эксплуатацию обрабатываются через подсистему MatterCommissioner в GHA.

  1. Следуя основной стратегии, используемой при анализе ошибок ввода в эксплуатацию, найдите ошибки, сгенерированные подсистемой MatterCommissioner, с помощью следующей команды:
$ grep "MatterCommissioner" <file-name>

Будет создан файл с событиями, произошедшими в процессе ввода в эксплуатацию.

  1. Если устройство Matter использует Thread, вы также можете найти ошибки, сгенерированные подсистемой Thread, с помощью следующей команды:
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

При анализе файла журнала, созданного в процессе отладки ADB, также ищите определенные закономерности. Многие ошибки ввода в эксплуатацию содержат строку "commissioning failure" в сообщении об ошибке.

  1. Найдите сообщение о сбое ввода в эксплуатацию с помощью следующей команды:
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"

4. Устранение неполадок с управлением устройствами

После того как пользователи настроят и введут в эксплуатацию устройства Matter в экосистеме Google Home, они смогут отдавать команды голосом с помощью Google Ассистента (например, "Окей, Google, включи свет в гостиной") или с помощью интерфейса в приложении Home или на дисплеях Google Nest.

Поскольку Matter выступает посредником между конечными устройствами и хабами Google, ожидается, что ошибок при управлении устройствами будет меньше. Тем не менее мы предоставляем показатели и журналы, которые помогут вам устранить неполадки.

Как использовать раздел "Показатели"

На панели интеграции Matter вы увидите несколько показателей, связанных с управлением устройствами. Для оценки эффективности устройств в полевых условиях важны три диаграммы:

Диаграммы с разбивкой по успешным запросам, задержке и ошибкам

При проблемах с управлением обычно наблюдается нисходящий тренд в проценте успешных загрузок и восходящий тренд на диаграмме ошибок. На диаграмме "Распределение ошибок" показаны ошибки, зарегистрированные Google Nest Hub, из-за которых не удалось выполнить попытку управления устройством.

Как использовать журналы

При каждой проблеме с управлением устройством Matter в системе создается журнал ошибок. Чтобы отфильтровать эти ошибки в Logs Explorer, выполните поиск по запросу executionLog.

Журналы ошибок управления устройствами Matter выглядят следующим образом:

{
  "insertId": "1a32ry0f6xpzzn",
  "jsonPayload": {
    "executionLog": {
      "executionResults": [
        {
          "executionType": "MATTER",
          "latencyMsec": "6000",
          "actionResults": [
            {
              "action": {
                "actionType": "ONOFF_OFF",
                "trait": "TRAIT_ON_OFF"
              },
              "status": {
                "externalDebugString": "No message was received before the deadline.",
                "statusType": "RESPONSE_TIMEOUT",
                "fallbackToCloud": false,
                "isSuccess": false
              },
              "device": {
                "deviceType": "OUTLET"
              }
            }
          ],
          "requestId": "1487232799486580805"
        }
      ]
    },
    "locale": "en-US"
  },
  "resource": {
    "type": "assistant_action_project",
    "labels": {
      "project_id": "<project-id>"
    }
  },
  "timestamp": "2023-03-01T15:47:27.311673018Z",
  "severity": "ERROR",
  "logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
  "receiveTimestamp": "2023-03-01T15:47:27.311673018Z"
}

Каждая запись в журнале ошибок содержит временную метку, тип устройства и признак, а также ошибку, связанную с запросом на управление в statusType. Многие ошибки управления также включают externalDebugString – короткое сообщение об ошибке, объясняющее суть ошибки.

5. Отладка других функций

Вы узнали, как решать проблемы с вводом в эксплуатацию и управлением устройствами Matter. В экосистеме есть и другие функции, которые вы можете использовать, а также рекомендуемые методы, которые помогут обеспечить высокое качество интеграции.

Как отслеживать беспроводные обновления

Чтобы отслеживать беспроводные обновления устройств Matter, выпущенные Google Home, мы предоставляем набор показателей, которые отражают версии аппаратного и программного обеспечения устройств, находящихся в эксплуатации.

После выпуска обновления в консоли следите за следующими показателями:

Сбои программного и аппаратного обеспечения

В течение нескольких дней после выпуска вы увидите, что все больше устройств получают новую версию ПО, связанную с вашим выпуском ПО OTA.

6. Обратитесь за поддержкой

Google предоставляет инструменты и документацию для устранения неполадок с Matter. Однако экосистема Matter появилась недавно, поэтому в ней могут возникать проблемы, не описанные в этих ресурсах. В таких случаях вы всегда можете обратиться за помощью к нам или сообществу.

Посетите каналы для разработчиков

В Google активно отслеживаются три канала для разработчиков:

Stack Overflow, система отслеживания ошибок, форум разработчиков

Хотя все эти каналы периодически проверяются одной и той же командой, есть некоторые ключевые различия в том, когда какой из них использовать.

  • Stack Overflow. Вы можете обратиться к нам и сообществу разработчиков умного дома с вопросами о реализации или за рекомендациями. Этот канал лучше всего подходит для того, чтобы задавать вопросы об устранении неполадок или реализации определенных функций.
  • Система отслеживания ошибок. Это официальная система отслеживания ошибок, управляемая Google, в которой внешние пользователи могут сообщать об ошибках в экосистеме. В нем есть веб-инструменты, позволяющие прикреплять файлы и делиться конфиденциальной информацией. Система отслеживания ошибок – лучший способ сообщить о проблемах в экосистеме или отправить запрос на добавление функции.
  • Форум для разработчиков. Чтобы получить помощь от официальной службы поддержки Google и экспертов сообщества, вы можете обратиться к ним на форуме для разработчиков Nest. Здесь вы можете получить официальные рекомендации по разработке.

Подписаться на новостную рассылку для разработчиков

Помимо каналов для разработчиков, где можно задавать вопросы, мы также выпускаем ежеквартальную новостную рассылку, в которой рассказываем о новых функциях и новостях экосистемы Google Умный дом.

Чтобы получать новости для разработчиков, заполните форму регистрации.

7. Поздравляю!

Устройства экосистемы умного дома Google Home

Поздравляем! Вы узнали, как отлаживать интеграции Matter с помощью рекомендуемых инструментов и методов. Желаем успехов в создании умного дома с Matter и Google Home!

Дальнейшие действия

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

  • Помимо аналитики, для устранения неполадок можно использовать набор тестов, который позволяет проверить интеграцию на наличие потенциальных проблем.
  • Когда интеграция будет готова, вам нужно будет получить сертификат "Работает с Google Home". Для этого следуйте инструкциям на странице Сертификация.