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

Требования
- Руководство для разработчиков по созданию интеграции Cloud-to-cloud
- Практическая работа Стиральная машина в умном доме
- Руководство для разработчиков по локальному выполнению
Что вы создадите
В этой практической работе вы развернете ранее созданную интеграцию умного дома с Firebase, затем примените конфигурацию сканирования в Developer Console и создадите локальное приложение на TypeScript для отправки команд, написанных на Node.js, на виртуальную стиральную машину.
Что вы узнаете
- Как включить и настроить локальное выполнение в Developer Console.
- Как использовать Local Home SDK для написания приложения для локального выполнения.
- Как отладить приложение для локального выполнения, загруженное на колонку Google Home или умный дисплей Google Nest.
Что вам понадобится
- Последняя версия Google Chrome.
- Устройство iOS или Android с приложением Google Home.
- Умная колонка Google Home или умный дисплей Google Nest.
- Node.js версии 24 или более поздней.
- Аккаунт Google.
- Платежный аккаунт Google Cloud.
- Тарифный план Blaze (оплата по мере использования) для Firebase.
2. Начало работы
Как включить отслеживание действий
Чтобы использовать Google Ассистента, вы должны предоставить Google доступ к определенным данным о своих действиях. Эти данные необходимы для правильной работы Google Ассистента, однако требование об их передаче не связано с SDK. Чтобы поделиться этими данными, создайте аккаунт Google, если у вас его ещё нет. Вы можете использовать любой аккаунт Google, не обязательно аккаунт разработчика.
Откройте страницу Отслеживание действий для аккаунта Google, который вы хотите использовать с Ассистентом.
Убедитесь, что включены следующие переключатели:
- История приложений и веб-поиска. Также установите флажок Также сохранять историю Chrome и данные о действиях на сайтах, в приложениях и на устройствах, которые используют сервисы Google.
- Информация об устройстве
- История голосового управления
Создайте проект интеграции Cloud-to-cloud
- Перейдите в Developer Console.
- Нажмите Создать проект, введите название проекта и нажмите Создать проект.

Выберите интеграцию Cloud-to-cloud
На главной странице проекта в Developer Console выберите Add cloud-to-cloud integration (Добавить интеграцию между облачными сервисами) в разделе Cloud-to-cloud (Облачные сервисы).

Установите интерфейс командной строки Firebase
Интерфейс командной строки Firebase (CLI) позволяет запускать веб-приложения локально и развертывать их в Firebase Hosting.
Чтобы установить CLI, выполните в терминале следующую команду npm:
npm install -g firebase-tools
Чтобы проверить, правильно ли установлен интерфейс командной строки, выполните следующую команду:
firebase --version
Авторизуйте интерфейс командной строки Firebase в аккаунте Google, выполнив следующую команду:
firebase login
Как включить HomeGraph API
HomeGraph API позволяет хранить и запрашивать информацию об устройствах и их статусах в Home Graph пользователя. Чтобы использовать этот API, сначала откройте консоль Google Cloud и включите HomeGraph API.
В консоли Google Cloud выберите проект, соответствующий вашей интеграции (<project-id>.). Затем на экране библиотеки API для HomeGraph API нажмите Включить.

3. Запустите шаблон приложения
Теперь, когда вы настроили среду разработки, вы можете развернуть базовый проект, чтобы убедиться, что все настроено правильно.
Получить исходный код
Чтобы скачать пример для этой практической работы на компьютер для разработки, нажмите на ссылку ниже.
…или клонируйте хранилище GitHub из командной строки:
git clone https://github.com/google-home/smarthome-local.git
О проекте
Начальный проект содержит следующие подкаталоги:
public– веб-интерфейс для управления умной стиральной машиной и отслеживания ее работы.functions– функции Cloud Functions, реализующие облачное выполнение для интеграции Cloud-to-cloud.local– проект приложения для локального выполнения с заглушками обработчиков намерений.index.ts
Предоставленное облачное выполнение включает следующие функции в index.js:
fakeauth– конечная точка авторизации для связывания аккаунтов.faketoken– конечная точка токена для связывания аккаунтов.smarthome– конечная точка выполнения намерений умного дома.reportstate– вызывает HomeGraph API при изменении состояния устройства.updateDevice– конечная точка, используемая виртуальным устройством для запуска Report State.
Установить связь с Firebase
Перейдите в каталог app-start и настройте интерфейс командной строки Firebase для проекта интеграции типа "облако – облако":
cd app-start firebase use <project-id>
Как настроить проект Firebase
Инициализируйте проект Firebase.
firebase init
Выберите функции CLI, Realtime Database и Functions.
? Which Firebase features do you want to set up for this directory? Press Space to select features, then Enter to confirm your choices. (Press <space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed) >( ) Data Connect: Set up a Firebase Data Connect service ( ) Firestore: Configure security rules and indexes files for Firestore ( ) Genkit: Setup a new Genkit project with Firebase (*) Functions: Configure a Cloud Functions directory and its files ( ) App Hosting: Configure an apphosting.yaml file for App Hosting ( ) Hosting: Configure files for Firebase Hosting and (optionally) set up GitHub Action deploys ( ) Storage: Configure a security rules file for Cloud Storage ( ) Emulators: Set up local emulators for Firebase products ( ) Remote Config: Configure a template file for Remote Config ( ) Extensions: Set up an empty Extensions manifest (*) Realtime Database: Configure a security rules file for Realtime Database and (optionally) provision default instance ( ) Data Connect: Set up a Firebase Data Connect service ( ) Firestore: Configure security rules and indexes files for Firestore
Это инициализирует необходимые API и функции для вашего проекта.
При появлении запроса инициализируйте Realtime Database. Вы можете использовать местоположение по умолчанию для экземпляра базы данных.
? It seems like you haven't initialized Realtime Database in your project yet. Do you want to set it up? Yes ? Please choose the location for your default Realtime Database instance: us-central1
Поскольку вы используете код начального проекта, выберите файл по умолчанию для правил безопасности и убедитесь, что вы не перезаписываете существующий файл правил базы данных.
? File database.rules.json already exists. Do you want to overwrite it with the Realtime Database Security Rules for <project-ID>-default-rtdb from the Firebase Console? No
Если вы повторно инициализируете проект, выберите Перезаписать, когда появится запрос на инициализацию или перезапись базы кода.
? Would you like to initialize a new codebase, or overwrite an existing one? Overwrite
При настройке функций используйте файлы по умолчанию и не перезаписывайте существующие файлы index.js и package.json в примере проекта.
? What language would you like to use to write Cloud Functions? JavaScript ? Do you want to use ESLint to catch probable bugs and enforce style? No ? File functions/package.json already exists. Overwrite? No ? File functions/index.js already exists. Overwrite? No
Если вы повторно инициализируете проект, выберите No (Нет), когда появится запрос на инициализацию или перезапись functions/.gitignore.
? File functions/.gitignore already exists. Overwrite? No
? Do you want to install dependencies with npm now? Yes
Если ESLint был включен случайно, его можно отключить двумя способами:
- В графическом интерфейсе пользователя перейдите в папку
../functionsв проекте, выберите скрытый файл.eslintrc.jsи удалите его. Не путайте его с похожим по названию.eslintrc.json. - В командной строке:
cd functions rm .eslintrc.js
Чтобы убедиться, что конфигурация Firebase правильная и полная, скопируйте файл firebase.json из каталога washer-done в каталог washer-start, перезаписав файл в каталоге washer-start.
В каталоге washer-start:
cp -vp ../washer-done/firebase.json .
Развертывание в Firebase
Теперь, когда вы установили зависимости и настроили проект, вы можете запустить приложение в первый раз.
firebase deploy
В консоли вы увидите следующее:
... ✔ Deploy complete! Project Console: https://console.firebase.google.com/project/<project-id>/overview Hosting URL: https://<project-id>.web.app
Эта команда развертывает веб-приложение и несколько функций Cloud Functions for Firebase.
Откройте URL хостинга в браузере (https://<project-id>.web.app), чтобы посмотреть веб-приложение. Вы увидите следующий интерфейс:

Этот веб-интерфейс представляет собой стороннюю платформу для просмотра или изменения состояний устройств. Чтобы начать заполнение базы данных информацией об устройствах, нажмите ОБНОВИТЬ. На странице ничего не изменится, но текущее состояние стиральной машины будет сохранено в базе данных.
Теперь нужно подключить развернутый облачный сервис к Google Ассистенту с помощью Developer Console.
Настройте проект в Developer Console
На вкладке Develop (Разработка) добавьте Display Name (Отображаемое название) для взаимодействия. Оно будет показываться в приложении Google Home.

В разделе Брендинг приложения загрузите файл png для значка приложения размером 144 x 144 пикселя и назовите его .

Чтобы включить связывание аккаунтов, используйте следующие настройки:
Идентификатор клиента |
|
Секретный код клиента |
|
URL авторизации |
|
URL токена |
|

В поле Cloud fulfillment URL (URL выполнения в облаке) введите URL функции Cloud Functions, которая обеспечивает выполнение намерений умного дома.
https://us-central1-<project-id>.cloudfunctions.net/smarthome

Нажмите Сохранить, чтобы сохранить конфигурацию проекта, а затем нажмите Далее: тестирование, чтобы включить тестирование в проекте.

Теперь вы можете начать реализацию вебхуков, необходимых для подключения состояния устройства к Ассистенту.
Связать с Google Ассистентом
Чтобы протестировать интеграцию Cloud-to-cloud, свяжите проект с аккаунтом Google. Это позволит вам тестировать действия на платформах Google Ассистента и в приложении Google Home, в которых выполнен вход в тот же аккаунт.
- Откройте настройки Google Ассистента на телефоне. Убедитесь, что вы вошли в тот же аккаунт, что и в консоли.
- Выберите Google Ассистент > Настройки > Управление домом (в разделе "Ассистент").
- Нажмите на значок поиска в правом верхнем углу.
- Чтобы найти тестовое приложение, введите в строку поиска префикс [test].
- Выберите его. Затем Google Ассистент выполнит аутентификацию в вашем сервисе и отправит запрос
SYNC, чтобы получить список устройств пользователя.
Откройте приложение Google Home и убедитесь, что стиральная машина видна в списке устройств.

Убедитесь, что вы можете управлять стиральной машиной с помощью голосовых команд в приложении Google Home. Вы также должны увидеть изменение состояния устройства в веб-интерфейсе вашего облачного выполнения.
Теперь вы можете добавить в интеграцию локальное выполнение.
4. Обновление облачного выполнения
Чтобы поддерживать локальное выполнение, вам нужно добавить новое поле для каждого устройства под названием otherDeviceIds в ответ облака SYNC, содержащий уникальный локальный идентификатор устройства. Это поле также указывает на возможность локального управления устройством.
Добавьте поле otherDeviceIds в ответ SYNC, как показано в следующем фрагменте кода:
functions/index.js
app.onSync((body) => {
return {
requestId: body.requestId,
payload: {
agentUserId: '123',
devices: [{
id: 'washer',
type: 'action.devices.types.WASHER',
traits: [ ... ],
name: { ... },
deviceInfo: { ... },
willReportState: true,
attributes: {
pausable: true,
},
otherDeviceIds: [{
deviceId: 'deviceid123',
}],
}],
},
};
});
Разверните обновленный проект в Firebase:
firebase deploy --only functions
После завершения развертывания перейдите в веб-интерфейс и нажмите кнопку Обновить
на панели инструментов. Это запустит операцию Request Sync, и Ассистент получит обновленные данные ответа SYNC.

5. Как настроить выполнение заказов на местном уровне
В этом разделе вы добавите необходимые параметры конфигурации для локального выполнения в интеграцию Cloud-to-cloud. В процессе разработки вы опубликуете приложение для локального выполнения в Firebase Hosting, откуда устройство Google Home сможет получить к нему доступ и скачать его.
В Google Home Developer Console в левой части экрана выберите Project (Проект) > Cloud-to-cloud (Облако – облако), а затем нажмите Edit (Изменить) для интеграции. На странице Настройка и конфигурация прокрутите до раздела Выполнение заказов на местном уровне и включите эту функцию. Вставьте в каждое поле тестового URL следующий URL, укажите идентификатор проекта и нажмите Сохранить:
https://<project-id>.web.app/local-home/index.html

Теперь нужно определить, как устройство Google Home должно обнаруживать локальные умные устройства. Платформа Local Home поддерживает несколько протоколов для обнаружения устройств, включая mDNS, UPnP и UDP. Вы будете использовать широковещательную рассылку UDP для обнаружения умной стиральной машины.
В разделе Обнаружение устройств нажмите + Добавить конфигурацию сканирования. Выберите UDP в качестве протокола и укажите следующие атрибуты:
Поле | Описание | Рекомендуемое значение |
Адрес обнаружения | Адрес обнаружения UDP |
|
Порт трансляции | Порт, на который Google Home отправляет широковещательные UDP-пакеты |
|
Порт прослушивания | Порт, через который Google Home ожидает ответ |
|
Пакет Discovery | Полезная нагрузка данных широковещательной рассылки UDP |
|

Нажмите Сохранить внизу окна, чтобы опубликовать изменения.
6. Как настроить местную доставку
Вы будете разрабатывать приложение для локального выполнения на TypeScript, используя пакет типизации Local Home SDK. Посмотрите на скелет, предоставленный в стартовом проекте:
local/index.ts
/// <reference types="@google/local-home-sdk" />
import App = smarthome.App;
import Constants = smarthome.Constants;
import DataFlow = smarthome.DataFlow;
import Execute = smarthome.Execute;
import Intents = smarthome.Intents;
import IntentFlow = smarthome.IntentFlow;
...
class LocalExecutionApp {
constructor(private readonly app: App) { }
identifyHandler(request: IntentFlow.IdentifyRequest):
Promise<IntentFlow.IdentifyResponse> {
// TODO: Implement device identification
}
executeHandler(request: IntentFlow.ExecuteRequest):
Promise<IntentFlow.ExecuteResponse> {
// TODO: Implement local fulfillment
}
...
}
const localHomeSdk = new App('1.0.0');
const localApp = new LocalExecutionApp(localHomeSdk);
localHomeSdk
.onIdentify(localApp.identifyHandler.bind(localApp))
.onExecute(localApp.executeHandler.bind(localApp))
.listen()
.then(() => console.log('Ready'))
.catch((e: Error) => console.error(e));
Основным компонентом локального выполнения является класс smarthome.App. Начальный проект прикрепляет обработчики для намерений IDENTIFY и EXECUTE, а затем вызывает метод listen(), чтобы сообщить Local Home SDK, что приложение готово.
Добавьте обработчик IDENTIFY
Local Home SDK запускает обработчик IDENTIFY, когда устройство Google Home обнаруживает в локальной сети неподтвержденные устройства на основе конфигурации сканирования, заданной в консоли разработчика.
Когда Google обнаруживает подходящее устройство, платформа вызывает identifyHandler с полученными данными сканирования. В вашем приложении сканирование выполняется с помощью широковещательной рассылки UDP, а данные сканирования, предоставляемые обработчику IDENTIFY, включают полезную нагрузку ответа, отправленную локальным устройством.
Обработчик возвращает экземпляр IdentifyResponse, содержащий уникальный идентификатор локального устройства. Добавьте следующий код в метод identifyHandler, чтобы обработать ответ UDP, поступающий от локального устройства, и определить соответствующий идентификатор локального устройства:
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');
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);
}
Обратите внимание, что поле verificationId должно соответствовать одному из значений otherDeviceIds в ответе SYNC, который помечает устройство как доступное для локального выполнения в Home Graph пользователя. Если совпадение найдено, устройство считается подтвержденным и готовым к локальному выполнению.
Добавьте обработчик EXECUTE
Local Home SDK запускает обработчик EXECUTE, когда устройство с поддержкой локального выполнения получает команду. Содержимое локального намерения эквивалентно намерению EXECUTE, отправленному в ваше облачное выполнение, поэтому логика локальной обработки намерения напоминает то, как вы обрабатываете его в облаке.Действия
Приложение может использовать сокеты TCP/UDP или запросы HTTP(S) для связи с локальными устройствами. В этой практической работе HTTP используется в качестве протокола для управления виртуальным устройством. Номер порта определяется в index.ts как переменная SERVER_PORT.
Добавьте следующий код в метод executeHandler, чтобы обрабатывать входящие команды и отправлять их на локальное устройство по протоколу HTTP:
local/index.ts
executeHandler(request: IntentFlow.ExecuteRequest):
Promise<IntentFlow.ExecuteResponse> {
console.log("EXECUTE intent: " + JSON.stringify(request, null, 2));
const command = request.inputs[0].payload.commands[0];
const execution = command.execution[0];
const response = new Execute.Response.Builder()
.setRequestId(request.requestId);
const promises: Array<Promise<void>> = command.devices.map((device) => {
console.log("Handling EXECUTE intent for device: " + JSON.stringify(device));
// Convert execution params to a string for the local device
const params = execution.params as IWasherParams;
const payload = this.getDataForCommand(execution.command, params);
// Create a command to send over the local network
const radioCommand = new DataFlow.HttpRequestData();
radioCommand.requestId = request.requestId;
radioCommand.deviceId = device.id;
radioCommand.data = JSON.stringify(payload);
radioCommand.dataType = 'application/json';
radioCommand.port = SERVER_PORT;
radioCommand.method = Constants.HttpOperation.POST;
radioCommand.isSecure = false;
console.log("Sending request to the smart home device:", payload);
return this.app.getDeviceManager()
.send(radioCommand)
.then(() => {
const state = {online: true};
response.setSuccessState(device.id, Object.assign(state, params));
console.log(`Command successfully sent to ${device.id}`);
})
.catch((e: IntentFlow.HandlerError) => {
e.errorCode = e.errorCode || 'invalid_request';
response.setErrorState(device.id, e.errorCode);
console.error('An error occurred sending the command', e.errorCode);
});
});
return Promise.all(promises)
.then(() => {
return response.build();
})
.catch((e) => {
const err = new IntentFlow.HandlerError(request.requestId,
'invalid_request', e.message);
return Promise.reject(err);
});
}
Компиляция приложения TypeScript
Перейдите в каталог local/ и выполните следующие команды, чтобы скачать компилятор TypeScript и скомпилировать приложение:
cd local npm install npm run build
Это компилирует исходный код index.ts (TypeScript) и помещает следующее содержимое в каталог public/local-home/:
bundle.js– скомпилированный код JavaScript, содержащий локальное приложение и зависимости.index.html– страница локального хостинга, используемая для показа приложения при тестировании на устройстве.
Разверните тестовый проект
Разверните обновленные файлы проекта в Firebase Hosting, чтобы получить к ним доступ с устройства Google Home.
firebase deploy --only hosting
7. Запустить умную стиральную машину
Теперь давайте проверим связь между приложением для локального выполнения и умной стиральной машиной. В начальном проекте практической работы есть виртуальная умная стиральная машина, написанная на Node.js. Она имитирует умную стиральную машину, которой пользователи могут управлять локально.
Настройте устройство
Вам нужно настроить виртуальное устройство так, чтобы оно использовало те же параметры UDP, которые вы применили к конфигурации сканирования для обнаружения устройств в Developer Console. Кроме того, вам нужно указать, какой идентификатор локального устройства должно передавать виртуальное устройство и какой идентификатор проекта облачной интеграции использовать для событий Report State при изменении состояния устройства.
Параметр | Рекомендуемое значение |
deviceId |
|
discoveryPortOut |
|
discoveryPacket |
|
projectId | Идентификатор проекта интеграции умного дома. |
Запустите устройство.
Перейдите в каталог 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
8. Отладка приложения TypeScript
В следующем разделе вы проверите, может ли устройство Google Home правильно сканировать, идентифицировать и отправлять команды виртуальной умной стиральной машине по локальной сети. Вы можете использовать инструменты разработчика в Google Chrome, чтобы подключиться к устройству Google Home, посмотреть журналы консоли и выполнить отладку приложения TypeScript.
Как подключить инструменты разработчика в Chrome
Чтобы подключить отладчик к локальному приложению, выполните следующие действия:
- Убедитесь, что устройство Google Home связано с пользователем, у которого есть разрешение на доступ к проекту Developer Console.
- Перезагрузите устройство Google Home, чтобы оно получило URL HTML-файла и конфигурацию сканирования, которую вы указали в Developer Console.
- Запустите Chrome на компьютере для разработки.
- Откройте новую вкладку в Chrome и введите
chrome://inspectв адресной строке, чтобы запустить инспектор.
Вы увидите список устройств, а под названием устройства Google Home – URL приложения.

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

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

Убедитесь, что состояние стиральной машины меняется после каждой команды.
... ***** The washer is RUNNING ***** ... ***** The washer is STOPPED *****
9. Поздравляю!

Поздравляем! Вы использовали Local Home SDK, чтобы интегрировать локальное выполнение в интеграцию типа "облако – облако".
Подробнее…
Вот что ещё можно сделать:
- Измените конфигурацию сканирования и запустите его. Например, попробуйте использовать другой UDP-порт или пакет обнаружения.
- Измените базу кода виртуального умного устройства, чтобы запустить его на встроенном устройстве, например Raspberry Pi, и используйте светодиоды или дисплей для визуализации текущего состояния.