Отладка локального дома

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

Интеграция с умным домом позволяет Google Ассистенту управлять подключенными устройствами в домах пользователей. Чтобы создать облачную интеграцию, вам нужно предоставить конечную точку вебхука, способную обрабатывать намерения умного дома. Например, когда пользователь говорит "Окей, Google, включи свет", Ассистент отправляет команду в облако, чтобы изменить состояние устройства.

Local Home SDK улучшает интеграцию умного дома, добавляя локальный путь для маршрутизации действий умного дома непосредственно на устройство Google Home, что повышает надежность и сокращает задержку при обработке команд пользователей. Она позволяет написать и развернуть приложение для локального выполнения на TypeScript или JavaScript, которое идентифицирует устройства и выполняет команды на любой умной колонке Google Home или умном дисплее Google Nest. Затем ваше приложение напрямую связывается с умными устройствами пользователей по локальной вычислительной сети, используя существующие стандартные протоколы для выполнения команд.

72ffb320986092c.png

Отладка облачных интеграций – важный этап, который позволяет обеспечить их качество. Однако без информативных и простых в использовании инструментов для тестирования и устранения неполадок этот процесс может быть сложным и занимать много времени. Чтобы упростить отладку облачных интеграций, вы можете использовать Metrics, Logging и набор тестов для умного дома. Эти инструменты Google Cloud помогут вам выявлять и устранять проблемы с интеграциями.

Требования

Что вы создадите

В этой практической работе вы создадите локальное выполнение для интеграций типа "облако – облако " и подключите его к Ассистенту, а затем отладите приложение Local Home с помощью набора тестов для умного дома, а также Google Cloud Metrics и Logging.

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

  • Как использовать Google Cloud Metrics и Logging для выявления и устранения проблем в рабочей среде.
  • Как использовать набор тестов для выявления проблем с функциями и API.
  • Как использовать инструменты разработчика Chrome при создании приложения Local Home.

Что вам понадобится

2. Запустить приложение для стиральной машины

Как получить исходный код

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

…или клонируйте хранилище GitHub из командной строки:

$ git clone https://github.com/google-home/smarthome-debug-local.git

О проекте

Стартовое приложение содержит те же подкаталоги и Cloud Functions, что и в практической работе Включение локального выполнения для интеграций типа "облако-облако". Но вместо app-start у нас здесь app-faulty. Мы начнем с локального приложения Home, которое работает, но не очень хорошо.

Установить связь с Firebase

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

Перейдите в каталог app-faulty и настройте интерфейс командной строки Firebase с помощью проекта интеграции, созданного в практической работе Как включить локальное выполнение для облачных интеграций.

$ cd app-faulty
$ firebase use <project-id>

Развертывание в Firebase

Перейдите в папку app-faulty/functions и установите все необходимые зависимости с помощью npm:

$ cd functions
$ npm install

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

found 5 high severity vulnerabilities
  run `npm audit fix` to fix them, or `npm audit` for details

Перейдите в каталог app-faulty/local/ и выполните следующие команды, чтобы скачать компилятор TypeScript и скомпилировать приложение:

$ cd ../local
$ npm install
$ npm run build

Это компилирует исходный код index.ts (TypeScript) и помещает следующее содержимое в каталог app-faulty/public/local-home/:

  • bundle.js – скомпилированный код JavaScript, содержащий локальное приложение и зависимости.
  • index.html – страница локального хостинга, используемая для показа приложения при тестировании на устройстве.

Теперь, когда вы установили зависимости и настроили проект, вы можете запустить приложение в первый раз.

$ firebase deploy

В консоли вы увидите следующее:

...

✔ Deploy complete!

Project Console: https://console.firebase.google.com/project/<project-id>/overview
Hosting URL: https://<projectcd -id>.web.app

Эта команда развертывает веб-приложение и несколько функций Cloud Functions for Firebase.

Обновление HomeGraph

Откройте URL хостинга в браузере (https://<project-id>.web.app), чтобы посмотреть веб-приложение. В веб-интерфейсе нажмите кнопку Обновитьae8d3b25777a5e30.png, чтобы обновить HomeGraph, добавив в него последние метаданные устройства из приложения неисправной стиральной машины с помощью Request Sync.

fa3c47f293cfe0b7.png

Откройте приложение Google Home и убедитесь, что стиральная машина отображается под новым названием "Faulty Washer". Не забудьте назначить устройство комнате, в которой есть устройство Nest.

2a082ee11d47ad1a.png

3. Запустить умную стиральную машину

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

Запустите устройство.

Перейдите в каталог virtual-device/ и запустите скрипт устройства, передав параметры конфигурации в качестве аргументов:

$ cd ../../virtual-device
$ npm install
$ npm start -- \
  --deviceId=deviceid123 --projectId=<project-id> \
  --discoveryPortOut=3311 --discoveryPacket=HelloLocalHomeSDK

Убедитесь, что скрипт устройства выполняется с ожидаемыми параметрами:

(...): UDP Server listening on 3311
(...): Device listening on port 3388
(...): Report State successful

4. Тестирование приложения Local Home

Отправляйте голосовые команды на устройство Google Home, например:

"Окей, Google, включи стиральную машину".

"Окей, Google, запусти стиральную машину".

"Окей, Google, принудительно включи локальный режим".

"Окей, Google, останови стиральную машину".

Вы заметите, что Google Ассистент отвечает "Извините, похоже, что неисправная стиральная машина сейчас недоступна", когда вы пытаетесь управлять стиральной машиной после "принудительного локального".

Это означает, что устройство недоступно по локальному пути. До команды "Окей, Google, принудительно использовать локальный путь" все работало, потому что, когда устройство недоступно по локальному пути, мы переключаемся на облачный. Однако после принудительного использования локального пути резервный вариант с облачным путем будет отключен.

Чтобы выяснить, в чем проблема, используйте доступные инструменты: Metrics и Logging в Google Cloud, а также инструменты разработчика в Chrome.

5. Отладка приложения Local Home

В следующем разделе вы будете использовать инструменты, предоставляемые Google, чтобы выяснить, почему устройство недоступно по локальному пути. Вы можете использовать инструменты разработчика в Google Chrome, чтобы подключиться к устройству Google Home, посмотреть журналы консоли и отладить приложение Local Home. Вы также можете отправлять пользовательские журналы в Cloud Logging, чтобы быть в курсе основных ошибок, которые пользователи находят в вашем приложении Local Home.

Как подключить инструменты разработчика в Chrome

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

  1. Убедитесь, что устройство Google Home связано с пользователем, у которого есть разрешение на доступ к проекту Developer Console.
  2. Перезагрузите устройство Google Home, чтобы оно получило URL HTML-файла и конфигурацию сканирования, которую вы указали в Developer Console.
  3. Запустите Chrome на компьютере для разработки.
  4. Откройте новую вкладку в Chrome и введите chrome://inspect в адресной строке, чтобы запустить инспектор.

Вы увидите список устройств, а под названием устройства Google Home – URL приложения.

567f97789a7d8846.png

Как запустить инспектор

Нажмите Проверить под URL приложения, чтобы запустить Инструменты разработчика в Chrome. Выберите вкладку Консоль и убедитесь, что вы видите контент намерения IDENTIFY, напечатанный вашим приложением TypeScript.

774c460c59f9f84a.png

Этот вывод означает, что обработчик IDENTIFY был успешно запущен, но verificationId, возвращенный в IdentifyResponse, не соответствует ни одному из устройств в вашем HomeGraph. Теперь добавьте пользовательские журналы, чтобы выяснить причину.

Добавление пользовательских журналов

Хотя Local Home SDK выводит ошибку DEVICE_VERIFICATION_FAILED, это не помогает найти основную причину. Добавьте несколько пользовательских журналов, чтобы убедиться, что мы правильно считываем и обрабатываем данные сканирования. Обратите внимание, что если мы отклоним обещание с ошибкой, сообщение об ошибке также будет отправлено в Cloud Logging.

local/index.ts

identifyHandler(request: IntentFlow.IdentifyRequest):
    Promise<IntentFlow.IdentifyResponse> {
  console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));

  const scanData = request.inputs[0].payload.device.udpScanData;
  if (!scanData) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_request', 'Invalid scan data');
    return Promise.reject(err);
  }

  // In this codelab, the scan data contains only local device id.
  // Is there something wrong here?
  const localDeviceId = Buffer.from(scanData.data);
  console.log(`IDENTIFY handler: received local device id
      ${localDeviceId}`);

  // Add custom logs
  if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_device', 'Invalid device id from scan data ' +
        localDeviceId);
    return Promise.reject(err);
  }

  const response: IntentFlow.IdentifyResponse = {
    intent: Intents.IDENTIFY,
    requestId: request.requestId,
    payload: {
      device: {
        id: 'washer',
        verificationId: localDeviceId.toString(),
      }
    }
  };
  console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));

  return Promise.resolve(response);
}

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

local/index.ts

const localHomeSdk = new App('1.0.1');

После добавления специальных журналов необходимо снова скомпилировать приложение и повторно развернуть его в Firebase.

$ cd ../app-faulty/local
$ npm run build
$ firebase deploy --only hosting

Теперь перезагрузите устройство Google Home, чтобы оно могло загрузить обновленное приложение Home. Вы можете проверить, использует ли устройство Google Home ожидаемую версию, просмотрев журналы консоли в инструментах разработчика в Chrome.

ecc56508ebcf9ab.png

Как получить доступ к Cloud Logging

Затем узнайте, как использовать Cloud Logging для поиска ошибок. Чтобы получить доступ к Cloud Logging для проекта, выполните следующие действия:

  1. В консоли Cloud Platform перейдите на страницу Проекты.
  2. Выберите проект умного дома.
  3. В разделе Operations (Операции) выберите Logging (Ведение журналов) > Logs Explorer (Проводник журналов).

Доступ к данным журналов для пользователей проекта интеграции регулируется с помощью Identity and Access Management (IAM). Подробнее о ролях и разрешениях для данных ведения журналов см. в разделе Контроль доступа в Cloud Logging.

Как использовать расширенные фильтры

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

Нажмите на переключатель Показать запрос. Он должен превратиться в поле Конструктор запросов. Введите jsonPayload.intent="IDENTIFY" в поле Конструктор запросов и нажмите кнопку Выполнить запрос.

4c0b9d2828ee2447.png

В результате вы получите все журналы ошибок, которые генерируются в обработчике IDENTIFY. Затем разверните последнюю ошибку. В обработчике IDENTIFY вы найдете errorCode и debugString, которые вы только что задали при отклонении промиса.

71f2f156c6887496.png

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

Исправьте ошибку

Вернемся к исходному коду, в котором мы анализируем идентификатор локального устройства на основе данных сканирования. Мы видим, что при преобразовании строки в байты не была указана кодировка. Данные сканирования поступают в виде шестнадцатеричной строки, поэтому при вызове Buffer.from() передайте hex в качестве кодировки символов.

local/index.ts

identifyHandler(request: IntentFlow.IdentifyRequest):
    Promise<IntentFlow.IdentifyResponse> {
  console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));

  const scanData = request.inputs[0].payload.device.udpScanData;
  if (!scanData) {
    const err = new IntentFlow.HandlerError(request.requestId,
        'invalid_request', 'Invalid scan data');
    return Promise.reject(err);
  }

  // In this codelab, the scan data contains only local device id.
  const localDeviceId = Buffer.from(scanData.data, 'hex');
  console.log(`IDENTIFY handler: received local device id
      ${localDeviceId}`);

  if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
    const err = new IntentFlow.HandlerError(request.requestId,
      'invalid_device', 'Invalid device id from scan data ' +
      localDeviceId);
    return Promise.reject(err);
  }

  const response: IntentFlow.IdentifyResponse = {
    intent: Intents.IDENTIFY,
    requestId: request.requestId,
    payload: {
      device: {
        id: 'washer',
        verificationId: localDeviceId.toString(),
      }
    }
  };
  console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));

  return Promise.resolve(response);
}

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

local/index.ts

const localHomeSdk = new App('1.0.2');

После исправления ошибки скомпилируйте приложение и повторно разверните его в Firebase. В app-faulty/local выполните следующую команду:

$ npm run build
$ firebase deploy --only hosting

Проверьте исправление

После развертывания перезагрузите устройство Google Home, чтобы оно могло загрузить обновленное приложение Home. Убедитесь, что версия приложения – 1.0.2. На этот раз в консоли инструментов разработчика в Chrome не должно быть ошибок.

c8456f7b5f77f894.png

Теперь вы можете снова попробовать отправить команды на устройство.

"Окей, Google, принудительно использовать локальный режим".

"Окей, Google, останови стиральную машину".

"Окей, Google, включи стиральную машину".

…

"Окей, Google, принудительно использовать по умолчанию".

6. Запустите набор тестов для умного дома

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

Запустите набор тестов для умного дома

Чтобы протестировать облачную интеграцию с помощью набора тестов, выполните следующие действия:

  1. В веб-браузере откройте набор тестов для умного дома.
  2. Войдите в аккаунт Google, нажав кнопку в правом верхнем углу. Это позволит набору тестов отправлять команды напрямую Google Ассистенту.
  3. В поле Project ID (Идентификатор проекта) введите идентификатор проекта интеграции типа "облако – облако". Затем нажмите Далее.
  4. На шаге Test Settings (Настройки тестирования) в разделе Devices and Traits (Устройства и функции) вы увидите Faulty Washer.
  5. Отключите параметр Test Request Sync (Проверить синхронизацию запросов), поскольку в примере приложения для стиральной машины нет интерфейса для добавления, удаления или переименования стиральной машины. В рабочей системе вы должны запускать запрос на синхронизацию каждый раз, когда пользователь добавляет, удаляет или переименовывает устройства.
  6. Оставьте параметр Local Home SDK включенным, поскольку мы будем тестировать как локальные, так и облачные пути.
  7. Нажмите Далее: тестовая среда, чтобы запустить тестирование.

67433d9190fa770e.png

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

d1ebd5cfae2a2a47.png

Проанализировать сообщение об ошибке

Внимательно изучите сообщения об ошибках в отчетах о тестировании. Они показывают, какое состояние ожидалось и какое было получено. В этом случае для команды "Приостановить стиральную машину" ожидаемое состояние – isPaused: true, а фактическое – isPaused: false. Аналогично для команды "Приостанови стиральную машину" ожидаемое состояние – isPaused: true, а фактическое – isPaused: false.

6bfd3acef9c16b84.png

Судя по сообщениям об ошибках, в локальном пути мы устанавливаем состояние isPaused наоборот.

Как выявить и устранить ошибку

Найдите исходный код, в котором приложение Local Home отправляет команду выполнения на устройство. getDataCommand() – функция, вызываемая executeHandler() для установки payload в команде выполнения, отправляемой на устройство.

local/index.ts

getDataForCommand(command: string, params: IWasherParams): unknown {
    switch (command) {
        case 'action.devices.commands.OnOff':
            return {
                on: params.on ? true : false
            };
        case 'action.devices.commands.StartStop':
            return {
                isRunning: params.start ? true : false
            };
        case 'action.devices.commands.PauseUnpause':
            return {
                // Is there something wrong here?
                isPaused: params.pause ? false : true
            };
        default:
            console.error('Unknown command', command);
            return {};
    }
}

Мы действительно задаем isPause в обратном состоянии. Значение должно быть true, когда params.pause – true, и false в противном случае. Чтобы устранить проблему, обновите условие.

local/index.ts

getDataForCommand(command: string, params: IWasherParams): unknown {
    switch (command) {
        case 'action.devices.commands.OnOff':
            return {
                on: params.on ? true : false
            };
        case 'action.devices.commands.StartStop':
            return {
                isRunning: params.start ? true : false
            };
        case 'action.devices.commands.PauseUnpause':
            return {
                isPaused: params.pause ? true : false
            };
        default:
            console.error('Unknown command', command);
            return {};
    }
}

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

local/index.ts

const localHomeSdk = new App('1.0.3');

Не забудьте снова скомпилировать приложение и развернуть его в Firebase. В app-faulty/local выполните следующую команду:

$ npm run build
$ firebase deploy --only hosting

Перезагрузите устройство Google Home, чтобы загрузить обновленное приложение Local Home. Убедитесь, что версия приложения – 1.0.3.

Проверьте исправление

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

b7fc8c5d3c727d8d.png

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

764dbc83b95782a.png

Поздравляем! Вы узнали, как устранять неполадки в приложении Local Home с помощью набора тестов для умного дома и Cloud Logging.

Подробнее

Вот что ещё можно сделать:

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