Чтобы поддерживать локальное выполнение, вам нужно создать приложение, которое будет обрабатывать следующие намерения умного дома:
IDENTIFY– поддерживает обнаружение умных устройств, которыми можно управлять локально. Обработчик намерений извлекает данные, которые ваше умное устройство возвращает во время обнаружения, и отправляет их в ответе Google.EXECUTE: поддерживает выполнение команд.QUERY: поддерживает запросы о состоянии устройства.REACHABLE_DEVICES– необязательный параметр, который позволяет обнаруживать конечные устройства с локальным управлением, подключенные к контроллеру или мосту.
Это приложение работает на устройствах Google Home или Google Nest и подключает ваше умное устройство к Ассистенту. Приложение можно создать на TypeScript (предпочтительно) или JavaScript.
Рекомендуется использовать TypeScript, поскольку вы можете использовать привязки, чтобы статически гарантировать, что данные, возвращаемые вашим приложением, соответствуют типам, ожидаемым платформой.
Дополнительную информацию об API можно найти в справочнике по Local Home SDK API.
В следующих фрагментах кода показано, как инициализировать приложение для локального выполнения и подключить обработчики.
import App = smarthome.App; const localHomeApp: App = new App("1.0.0"); localHomeApp .onIdentify(identifyHandler) .onExecute(executeHandler) .listen() .then(() => { console.log("Ready"); });
import App = smarthome.App; const localHomeApp: App = new App("1.0.0"); localHomeApp .onIdentify(identifyHandler) .onReachableDevices(reachableDevicesHandler) .onExecute(executeHandler) .listen() .then(() => { console.log("Ready"); });
Создайте проект
Чтобы развернуть приложение для локального выполнения, вам нужно создать пакет JavaScript для кода и всех его зависимостей.
Используйте инициализатор проекта приложения для локального выполнения, чтобы создать подходящую структуру проекта с нужной конфигурацией сборщика.
Шаблоны проектов
Чтобы выбрать конфигурацию сборщика, выполните команду npm init, как показано в примерах ниже.
TypeScript без конфигурации сборщика:
npm init @google/local-home-app project-directory/ --bundler none
Структура проекта:
project-directory/ ├── node_modules/ ├── package.json ├── .gitignore ├── index.ts ├── test.ts ├── tsconfig.json ├── tslint.json └── serve.js
Замените project-directory новым каталогом, который будет содержать проект приложения для локального выполнения.
Конфигурация сборщика webpack для TypeScript:
npm init @google/local-home-app project-directory/ --bundler webpack
Структура проекта:
project-directory/ ├── node_modules/ ├── package.json ├── .gitignore ├── index.ts ├── test.ts ├── tsconfig.json ├── tslint.json ├── webpack.config.web.js ├── webpack.config.node.js └── serve.js
Замените project-directory новым каталогом, который будет содержать проект приложения для локального выполнения.
Конфигурация сборщика TypeScript с Rollup:
npm init @google/local-home-app project-directory/ --bundler rollup
Структура проекта:
project-directory/ ├── node_modules/ ├── package.json ├── .gitignore ├── index.ts ├── test.ts ├── tsconfig.json ├── tslint.json ├── rollup.config.js └── serve.js
Замените project-directory новым каталогом, который будет содержать проект приложения для локального выполнения.
Конфигурация сборщика TypeScript с Parcel:
npm init @google/local-home-app project-directory/ --bundler parcel
Структура проекта:
project-directory/ ├── node_modules/ ├── package.json ├── .gitignore ├── index.ts ├── test.ts ├── tsconfig.json ├── tslint.json └── serve.js
Замените project-directory новым каталогом, который будет содержать проект приложения для локального выполнения.
Как выполнять основные задачи на уровне проекта
Сгенерированный проект поддерживает следующие скрипты npm:
cd project-directory/ npm run build
Этот скрипт компилирует исходный код TypeScript и связывает приложение с его зависимостями для среды выполнения Chrome в подкаталоге dist/web и среды выполнения Node.js в подкаталоге dist/node.
cd project-directory/ npm run lint npm run compile npm test
Этот скрипт проверяет синтаксис кода TypeScript, компилирует его, не создавая выходных данных в подкаталоге dist/, и запускает автоматические тесты из test.ts.
cd project-directory/ npm run start
Во время разработки этот скрипт локально обслуживает пакеты приложений для сред выполнения Chrome и Node.js.
Реализуйте обработчик IDENTIFY
Обработчик IDENTIFY будет активирован, когда устройство Google Home или устройство Google Nest перезагрузится и обнаружит непроверенные локальные устройства (включая конечные устройства, подключенные к контроллеру). Платформа Local Home выполнит поиск локальных устройств, используя указанные вами ранее настройки сканирования, и вызовет обработчик IDENTIFY с результатами сканирования.
Объект IdentifyRequest платформы Local Home содержит данные сканирования экземпляра LocalIdentifiedDevice. Заполняется только один экземпляр device на основе конфигурации сканирования, которая обнаружила устройство.
Если результаты сканирования соответствуют вашему устройству, обработчик IDENTIFY должен вернуть объект IdentifyResponsePayload, который включает объект device с метаданными умного дома (например, типы, характеристики и состояние отчета).
Google устанавливает связь с устройством, если значение verificationId из ответа IDENTIFY совпадает с одним из значений otherDeviceIds, возвращенных в ответе SYNC.
Пример
В следующих фрагментах кода показано, как создать обработчики IDENTIFY для интеграции отдельных устройств и контроллеров.
const identifyHandler = (request: IntentFlow.IdentifyRequest): IntentFlow.IdentifyResponse => { // Obtain scan data from protocol defined in your scan config const device = request.inputs[0].payload.device; if (device.udpScanData === undefined) { throw Error("Missing discovery response"); } const scanData = device.udpScanData.data; // Decode scan data to obtain metadata about local device const verificationId = "local-device-id"; // Return a response const response: IntentFlow.IdentifyResponse = { intent: Intents.IDENTIFY, requestId: request.requestId, payload: { device: { id: device.id || "", verificationId, // Must match otherDeviceIds in SYNC response }, }, }; return response; };
const identifyHandler = (request: IntentFlow.IdentifyRequest): IntentFlow.IdentifyResponse => { // Obtain scan data from protocol defined in your scan config const device = request.inputs[0].payload.device; if (device.udpScanData === undefined) { throw Error("Missing discovery response"); } const scanData = device.udpScanData.data; // Decode scan data to obtain metadata about local device const proxyDeviceId = "local-hub-id"; // Return a response const response: IntentFlow.IdentifyResponse = { intent: Intents.IDENTIFY, requestId: request.requestId, payload: { device: { id: proxyDeviceId, isProxy: true, // Device can control other local devices isLocalOnly: true, // Device not present in `SYNC` response }, }, }; return response; };
Как идентифицировать устройства, подключенные к концентратору
Если Google идентифицирует устройство-концентратор, оно будет рассматриваться как канал связи с подключенными к нему конечными устройствами. Google попытается проверить эти конечные устройства.
Чтобы Google мог подтвердить наличие контроллера, выполните следующие инструкции для обработчика IDENTIFY:
- Если в ответе
SYNCуказаны идентификаторы локальных конечных устройств, подключенных к хабу, задайте дляisProxyзначениеtrueвIdentifyResponsePayload. - Если в ответе
SYNCне указан контроллер, задайте дляisLocalOnlyзначениеtrueвIdentifyResponsePayload. - Поле
device.idсодержит идентификатор локального устройства для самого концентратора.
Реализуйте обработчик REACHABLE_DEVICES (только для интеграции контроллеров)
Интент REACHABLE_DEVICES отправляется Google, чтобы подтвердить, какими конечными устройствами можно управлять локально. Это намерение активируется каждый раз, когда Google запускает сканирование для обнаружения (примерно раз в минуту), если концентратор находится в сети.
Обработчик REACHABLE_DEVICES реализуется аналогично обработчику IDENTIFY, но должен собирать дополнительные идентификаторы устройств, доступных через локальный прокси-сервер (то есть хаб). Поле device.verificationId содержит локальный идентификатор устройства для конечного устройства, подключенного к концентратору.
Объект ReachableDevicesRequest из платформы Local Home содержит экземпляр LocalIdentifiedDevice.
Через этот экземпляр вы можете получить идентификатор прокси-устройства, а также данные из результатов сканирования.
Обработчик REACHABLE_DEVICES должен возвращать объект ReachableDevicesPayload, который включает объект devices, содержащий массив значений verificationId, представляющих конечные устройства, которыми управляет хаб. Значения verificationId должны соответствовать одному из значений otherDeviceIds из ответа SYNC.
В следующем фрагменте кода показано, как создать обработчик REACHABLE_DEVICES.
const reachableDevicesHandler = (request: IntentFlow.ReachableDevicesRequest): IntentFlow.ReachableDevicesResponse => { // Reference to the local proxy device const proxyDeviceId = request.inputs[0].payload.device.id; // Gather additional device ids reachable by local proxy device // ... const reachableDevices = [ // Each verificationId must match one of the otherDeviceIds // in the SYNC response { verificationId: "local-device-id-1" }, { verificationId: "local-device-id-2" }, ]; // Return a response const response: IntentFlow.ReachableDevicesResponse = { intent: Intents.REACHABLE_DEVICES, requestId: request.requestId, payload: { devices: reachableDevices, }, }; return response; };
Реализуйте обработчик EXECUTE
Обработчик EXECUTE в приложении обрабатывает команды пользователя и использует Local Home SDK для доступа к умным устройствам по существующему протоколу.
Платформа Local Home передает в функцию обработчика EXECUTE те же полезные данные, что и в намерение EXECUTE для облачного выполнения. Аналогично, обработчик EXECUTE возвращает выходные данные в том же формате, что и при обработке намерения EXECUTE.
Чтобы упростить создание ответа, вы можете использовать класс Execute.Response.Builder, который предоставляет Local Home SDK.
У вашего приложения нет прямого доступа к IP-адресу устройства. Вместо этого используйте интерфейс CommandRequest, чтобы создавать команды на основе одного из следующих протоколов: UDP, TCP или HTTP. Затем вызовите функцию deviceManager.send(), чтобы отправить команды.
При таргетинге команд на устройства используйте идентификатор устройства (и параметры из поля customData, если оно включено) из ответа SYNC для связи с устройством.
Пример
В следующем фрагменте кода показано, как создать обработчик EXECUTE.
const executeHandler = (request: IntentFlow.ExecuteRequest): Promise<IntentFlow.ExecuteResponse> => { // Extract command(s) and device target(s) from request const command = request.inputs[0].payload.commands[0]; const execution = command.execution[0]; const response = new Execute.Response.Builder() .setRequestId(request.requestId); const result = command.devices.map((device) => { // Target id of the device provided in the SYNC response const deviceId = device.id; // Metadata for the device provided in the SYNC response // Use customData to provide additional required execution parameters const customData: any = device.customData; // Convert execution command into payload for local device let devicePayload: string; // ... // Construct a local device command over TCP const deviceCommand = new DataFlow.TcpRequestData(); deviceCommand.requestId = request.requestId; deviceCommand.deviceId = deviceId; deviceCommand.data = devicePayload; deviceCommand.port = customData.port; deviceCommand.operation = Constants.TcpOperation.WRITE; // Send command to the local device return localHomeApp.getDeviceManager() .send(deviceCommand) .then((result) => { response.setSuccessState(result.deviceId, state); }) .catch((err: IntentFlow.HandlerError) => { err.errorCode = err.errorCode || IntentFlow.ErrorCode.INVALID_REQUEST; response.setErrorState(device.id, err.errorCode); }); }); // Respond once all commands complete return Promise.all(result) .then(() => response.build()); };
Реализуйте обработчик QUERY
Обработчик QUERY в приложении обрабатывает запросы пользователей и использует Local Home SDK, чтобы сообщать о состоянии умных устройств.
Платформа Local Home передает ту же полезную нагрузку запроса функции обработчика QUERY, что и для намерения QUERY, в облачный обработчик. Аналогично, обработчик QUERY возвращает данные в том же формате, что и при обработке намерения QUERY.
Отправка команд устройствам, подключенным к концентратору
Чтобы управлять конечными устройствами, подключенными к хабу, вам может потребоваться предоставить дополнительную информацию в полезной нагрузке команды, отправляемой на хаб. Это позволит хабу определить, для какого устройства предназначена команда. В некоторых случаях это можно определить по значению device.id, но если это не так, то необходимо включить дополнительные данные в поле customData.
Если вы создали приложение с помощью TypeScript, не забудьте скомпилировать его в JavaScript. Для написания кода можно использовать любую систему модулей. Убедитесь, что цель поддерживается браузером Chrome.