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

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

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

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

Ввод в эксплуатацию, выполнение, OTA-обновление

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

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

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

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

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

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

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

Доступ к метрикам проекта

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

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

Панели Google Home Analytics

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

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

Уровень успеха, задержка и разбивка по типам устройств

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

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

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

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

Открыв обозреватель журналов, вы увидите следующее представление:

Обозреватель журналов

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

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

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

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

Мероприятия по вводу дела в эксплуатацию

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

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

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

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

Показатели ввода устройства в эксплуатацию

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

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

  • КОМИССИЯ_СТАРТЕД
  • ONBOARDING_PAYLOAD_GENERATED
  • LOCAL_DISCOVERY_SUCCESSFUL
  • PASE_CONNECTION_SUCCESSFUL
  • NOC_ADDED_SUCCESSFULLY
  • КОМИССИЯ_COMPLETE

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

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

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

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

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

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

  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 Assistant (например, «Окей, Google, включи свет в моей гостиной») или с помощью пользовательского интерфейса приложения Home. или устройства отображения Google Nest.

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

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

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

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

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

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

Каждая проблема управления устройством 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 активно отслеживаются три канала разработчиков:

Переполнение стека, отслеживание проблем, форум разработчиков

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

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

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

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

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

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

Главная страница Google

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

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

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

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