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

Отладка облачных интеграций – важный этап, который позволяет обеспечить их качество. Однако без информативных и простых в использовании инструментов для тестирования и устранения неполадок этот процесс может быть сложным и занимать много времени. Чтобы упростить отладку облачных интеграций, вы можете использовать Metrics, Logging и набор тестов для умного дома. Эти инструменты Google Cloud помогут вам выявлять и устранять проблемы с интеграциями.
Требования
- Руководство для разработчиков по созданию интеграции Cloud-to-cloud
- Выполните практическую работу Как включить локальное выполнение для интеграций Cloud-to-cloud.
Что вы создадите
В этой практической работе вы создадите локальное выполнение для интеграций типа "облако – облако " и подключите его к Ассистенту, а затем отладите приложение Local Home с помощью набора тестов для умного дома, а также Google Cloud Metrics и Logging.
Что вы узнаете
- Как использовать Google Cloud Metrics и Logging для выявления и устранения проблем в рабочей среде.
- Как использовать набор тестов для выявления проблем с функциями и API.
- Как использовать инструменты разработчика Chrome при создании приложения Local Home.
Что вам понадобится
- Последняя версия Google Chrome.
- Устройство iOS или Android с приложением Google Home.
- Умная колонка Google Home или умный дисплей Google Nest.
- Node.js версии 24 или более поздней.
- Аккаунт Google.
- Платежный аккаунт Google Cloud.
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), чтобы посмотреть веб-приложение. В веб-интерфейсе нажмите кнопку Обновить
, чтобы обновить HomeGraph, добавив в него последние метаданные устройства из приложения неисправной стиральной машины с помощью Request Sync.

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

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
Чтобы подключить отладчик к локальному приложению, выполните следующие действия:
- Убедитесь, что устройство Google Home связано с пользователем, у которого есть разрешение на доступ к проекту Developer Console.
- Перезагрузите устройство Google Home, чтобы оно получило URL HTML-файла и конфигурацию сканирования, которую вы указали в Developer Console.
- Запустите Chrome на компьютере для разработки.
- Откройте новую вкладку в Chrome и введите
chrome://inspectв адресной строке, чтобы запустить инспектор.
Вы увидите список устройств, а под названием устройства Google Home – URL приложения.

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

Этот вывод означает, что обработчик 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.

Как получить доступ к Cloud Logging
Затем узнайте, как использовать Cloud Logging для поиска ошибок. Чтобы получить доступ к Cloud Logging для проекта, выполните следующие действия:
- В консоли Cloud Platform перейдите на страницу Проекты.
- Выберите проект умного дома.
- В разделе Operations (Операции) выберите Logging (Ведение журналов) > Logs Explorer (Проводник журналов).
Доступ к данным журналов для пользователей проекта интеграции регулируется с помощью Identity and Access Management (IAM). Подробнее о ролях и разрешениях для данных ведения журналов см. в разделе Контроль доступа в Cloud Logging.
Как использовать расширенные фильтры
Мы знаем, что ошибки возникают в намерении IDENTIFY, поскольку локальный путь не работает из-за того, что не удается идентифицировать локальное устройство. Однако мы хотим точно знать, в чем проблема, поэтому сначала отфильтруем ошибки, которые возникают в обработчике IDENTIFY.
Нажмите на переключатель Показать запрос. Он должен превратиться в поле Конструктор запросов. Введите jsonPayload.intent="IDENTIFY" в поле Конструктор запросов и нажмите кнопку Выполнить запрос.

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

Из 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 не должно быть ошибок.

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

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

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

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

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

Поздравляем! Вы узнали, как устранять неполадки в приложении Local Home с помощью набора тестов для умного дома и Cloud Logging.
Подробнее
Вот что ещё можно сделать:
- Добавьте больше поддерживаемых функций на устройство и проверьте их с помощью Test Suite.
- Добавьте больше пользовательских журналов в каждый из обработчиков намерений и просмотрите их в Cloud Logging.
- Создавайте панели управления, настраивайте оповещения и получайте доступ к данным показателей программным способом, чтобы получать полезные показатели использования вашей интеграции.
Вы также можете узнать больше о тестировании и отправке интеграции на проверку, включая процесс сертификации для публикации интеграции для пользователей.