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

1. Прежде чем начать

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

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

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

Предварительные требования

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

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

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

2. Просмотр Google Home Analytics

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

Доступ к показателям проекта

• Первый шаг для доступа к вашим данным — это проверка панелей мониторинга Google Home. Для этого войдите в Google Cloud Console и перейдите в раздел Operations > Monitoring > Dashboards .

Для вашего проекта (включая другие продукты GCP) доступен ряд панелей мониторинга. Панели мониторинга, предоставляемые для умного дома, имеют префикс Google Home Analytics.

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

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

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

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

Журналы ошибок доступа

Logs Explorer — это набор инструментов для работы с журналами событий, генерируемыми в проекте. Он доступен в консоли Google Cloud , перейдя в раздел Operations > Logging > Logs Explorer .

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

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

3. Отладка проблем, возникающих при вводе в эксплуатацию.

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

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

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

Используйте Google Home Analytics

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

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

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

Государства-партнеры:

• НАЧАЛО ВВОДА В ЭКСПЛУАТАЦИЮ
• ONBOARDING_PAYLOAD_GENERATED
• УСПЕШНОЕ ЛОКАЛЬНОЕ_ОТКРЫТИЕ
• PASE_CONNECTION_SUCCESSFUL
• NOC_ADDED_SUCCESSFULLY
• ВВОД В ЭКСПЛУАТАЦИЮ ЗАВЕРШЕН

Чтобы просмотреть подробную версию этих событий, перейдите в раздел «Операции» > «Ведение журналов» > «Проводник журналов» . Для фильтрации ошибок ввода в эксплуатацию можно выполнить поиск по запросу " 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

2. Подключите телефон к компьютеру, на котором запущен ADB-сервер.

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

3. Если вы получили это предупреждение, нажмите «Разрешить» .
4. Чтобы проверить, может ли ваш компьютер получить доступ к телефону через ADB, выполните команду list devices в терминале, используя следующую команду:

$ adb devices

В результате должен получиться примерно такой ответ:

List of devices attached
<phone-id>    device

Ваш <phone-id> — это буквенно-цифровая строка, которая однозначно идентифицирует ваше устройство.

5. Запомните значение <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 Services:

$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"

• Чтобы проверить наличие модулей управления «Дом»/«Материя» через Play Services:

$ 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 в эксплуатацию.

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

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

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

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

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

$ grep "MatterCommissioner" <file-name>

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

2. Если ваше устройство Matter использует Thread, вы также можете проверить наличие ошибок, генерируемых подсистемой Thread, с помощью следующей команды:

$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>

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

3. Найдите сообщение об ошибке ввода в эксплуатацию с помощью следующей команды:

$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"

4. Проблемы с отладкой управления устройством.

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

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

Используйте метрики

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

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

Используйте журналы

Каждая проблема с управлением устройством Matter также генерирует журнал ошибок в системе. Эти ошибки можно отфильтровать в обозревателе журналов, выполнив поиск по запросу " 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. В экосистеме также есть другие функции, которые вы можете использовать, или рекомендуемые методы для обеспечения качественной интеграции.

Отслеживайте обновления OTA

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

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

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

6. Обратитесь за помощью.

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

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

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

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

• Stack Overflow: Вы можете обратиться к нам и сообществу разработчиков Smart Home с вопросами по внедрению или за помощью. Этот канал лучше всего подходит для вопросов по устранению неполадок или реализации определенной функции .
• Система отслеживания ошибок (Issues Tracker): это официальная система отслеживания ошибок, управляемая Google, где внешние пользователи могут сообщать об ошибках в экосистеме. Она предоставляет веб-инструменты для прикрепления файлов и обмена конфиденциальной информацией при необходимости. Использование Issue Tracker — лучший способ сообщать о проблемах в экосистеме или делиться запросами на добавление новых функций .
• Форум разработчиков: Чтобы получить консультацию от официальной службы поддержки Google и экспертов сообщества, вы можете обратиться через форум разработчиков Nest. Этот форум лучше всего подходит для получения официальной консультации по разработке .

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

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

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

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

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

Следующие шаги

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

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