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

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

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

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

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

Предпосылки

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

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

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

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

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

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

• Первым шагом для доступа к вашим данным является проверка информационных панелей Google Home. Для этого войдите в Google Cloud Console и перейдите в раздел «Операции» > «Мониторинг» > «Информационные панели» .

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

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

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

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

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

Доступ к журналам ошибок

Logs Explorer — это набор инструментов для работы с журналами событий, созданными в проекте. Доступ к нему можно получить в Google Cloud Console , выбрав «Операции» > «Ведение журнала» > «Обозреватель журналов» .

После того, как вы откроете Logs Explorer, вы получите представление, которое выглядит следующим образом:

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

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

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

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

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

Используйте домашнюю аналитику Google

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

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

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

Государства ввода в эксплуатацию:

• ВВОД В ЭКСПЛУАТАЦИЮ_STARTED
• ONBOARDING_PAYLOAD_GENERATED
• LOCAL_DISCOVERY_SUCCESSFUL
• PASE_CONNECTION_УСПЕШНО
• 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, используя следующую команду:

$ 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:

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

• Чтобы проверить, есть ли у вас модули управления Home / Matter через 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.

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

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

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

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

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

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

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

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

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

7. Поздравления

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

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

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

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