Включите локальное выполнение для интеграции между облаками

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

Интеграция с системами «умного дома» позволяет Google Ассистенту управлять подключенными устройствами в домах пользователей. Для создания интеграции «облако-облако» необходимо предоставить конечную точку веб-перехватчика в облаке, способную обрабатывать намерения, связанные с «умным домом ». Например, когда пользователь говорит: «Привет, Google, включи свет», Ассистент отправляет команду в ваше облачное хранилище для обновления состояния устройства.

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

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

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

Что вы построите

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

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

• Как включить и настроить локальное выполнение заданий в консоли разработчика.
• Как использовать Local Home SDK для написания локального приложения для выполнения заказов.
• Как отладить локальное приложение для выполнения заказов, загруженное на колонку Google Home или умный дисплей Google Nest.

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

• Последняя версия Google Chrome
• Устройство iOS или Android с установленным приложением Google Home.
• Умная колонка Google Home или умный дисплей Google Nest.
• Node.js версии 10.16 или более поздней.
• Аккаунт Google
• Платежный аккаунт Google Cloud

2. Начало работы

Включить элементы управления активностью

Для использования Google Ассистента необходимо передавать Google определенные данные о действиях. Google Ассистент нуждается в этих данных для корректной работы; однако требование о передаче данных не является специфическим для SDK. Чтобы передать эти данные, создайте учетную запись Google , если у вас ее еще нет. Вы можете использовать любую учетную запись Google — это не обязательно должна быть ваша учетная запись разработчика.

Откройте страницу «Управление действиями» для учетной записи Google, которую вы хотите использовать с Ассистентом.

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

• Активность в Интернете и приложениях — Кроме того, обязательно установите флажок « Включать историю и активность Chrome с сайтов, приложений и устройств, использующих сервисы Google» .
• Информация об устройстве
• Голосовая и аудиоактивность

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

1. Перейдите в консоль разработчика .
2. Нажмите «Создать проект» , введите название проекта и нажмите «Создать проект» .

Выберите интеграцию «облако-облако».

На главной странице проекта в консоли разработчика выберите пункт «Добавить интеграцию между облаками» в разделе «Интеграция между облаками» .

Установите Firebase CLI.

Интерфейс командной строки Firebase (CLI) позволит вам запускать веб-приложения локально и развертывать их на хостинге Firebase.

Для установки CLI выполните следующую команду npm в терминале:

npm install -g firebase-tools

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

firebase --version

Авторизуйте Firebase CLI с помощью своей учетной записи Google, выполнив следующую команду:

firebase login

Включите API HomeGraph

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

В консоли Google Cloud убедитесь, что выбран проект, соответствующий идентификатору проекта <project-id>. Затем на экране «Библиотека API» для API HomeGraph нажмите «Включить» .

3. Запустите стартовое приложение.

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

Получите исходный код

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

file_download Скачать исходный код

...или вы можете клонировать репозиторий GitHub из командной строки:

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

О проекте

Стартовый проект содержит следующие подкаталоги:

• public — Веб-интерфейс для управления и мониторинга умной стиральной машины.
• functions — Облачные функции, реализующие облачное выполнение задач для интеграции между облачными сервисами.
• local — Проект приложения для локального выполнения заказов, в котором обработчики намерений заглушены в index.ts

Предоставляемое облачное решение включает следующие функции в index.js :

• fakeauth — Конечная точка авторизации для привязки учетных записей
• faketoken — Конечная точка для ввода токена для привязки учетной записи
• smarthome — конечная точка для выполнения задач в умном доме
• reportstate — Вызывает API HomeGraph при изменении состояния устройства
• updateDevice — конечная точка, используемая виртуальным устройством для запуска процесса формирования отчета о состоянии.

Подключитесь к Firebase

Перейдите в каталог app-start , затем настройте Firebase CLI для вашего проекта интеграции «облако-облако»:

cd app-start
firebase use <project-id>

Настройка проекта Firebase

Инициализируйте проект Firebase.

firebase init

Выберите функции командной строки, базу данных реального времени и функцию «Функции» .

? 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

Если вы выполняете повторную инициализацию проекта, выберите «Нет», когда вас спросят, хотите ли вы инициализировать или перезаписать файл functions/.gitignore.

? File functions/.gitignore already exists. Overwrite?
No

? Do you want to install dependencies with npm now?
Yes

Если ESLint был случайно включен, есть два способа его отключить:

1. С помощью графического интерфейса перейдите в папку ../functions внутри проекта, выберите скрытый файл .eslintrc.js и удалите его. Не путайте его с файлом .eslintrc.json имеющим аналогичное имя.
2. Использование командной строки:

   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

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

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

Этот веб-интерфейс представляет собой стороннюю платформу для просмотра или изменения состояния устройства. Чтобы начать заполнение базы данных информацией об устройстве, нажмите кнопку ОБНОВИТЬ . На странице не будет никаких изменений, но текущее состояние вашей стиральной машины будет сохранено в базе данных.

Теперь пришло время подключить развернутый вами облачный сервис к Google Ассистенту с помощью консоли разработчика.

Настройте свой проект в консоли разработчика.

На вкладке «Разработка» добавьте отображаемое имя для вашего взаимодействия. Это имя будет отображаться в приложении Google Home.

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

Для включения функции привязки учетных записей используйте следующие настройки привязки учетных записей:

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

https://us-central1-<project-id>.cloudfunctions.net/smarthome

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

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

Ссылка на Google Ассистент

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

1. На телефоне откройте настройки Google Ассистента. Обратите внимание, что вы должны войти в систему под той же учетной записью, что и в консоли.
2. Перейдите в Google Ассистент > Настройки > Управление домом (в разделе Ассистент).
3. Нажмите на значок поиска в правом верхнем углу.
4. Чтобы найти ваше тестовое приложение, используйте префикс [test] .
5. Выберите этот пункт. Затем Google Ассистент пройдет аутентификацию в вашем сервисе и отправит запрос SYNC , попросив ваш сервис предоставить пользователю список устройств.

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

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

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

4. Обновить облачное обслуживание.

Для поддержки локального выполнения необходимо добавить в ответ Cloud SYNC новое поле для каждого устройства под названием otherDeviceIds , содержащее уникальный локальный идентификатор устройства. Это поле также указывает на возможность локального управления данным устройством.

Добавьте поле 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

После завершения развертывания перейдите в веб-интерфейс и нажмите кнопку «Обновить». Кнопка на панели инструментов. Она запускает операцию запроса синхронизации, чтобы помощник получил обновленные данные ответа SYNC .

5. Настройка локального выполнения заказов

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

В консоли разработчика Google Home перейдите в раздел «Проект» > «Облако-облако» в левой части экрана, затем выберите «Редактировать» для интеграции. На странице «Настройка и конфигурация» прокрутите до пункта «Локальное выполнение» и включите эту настройку. Введите следующий URL-адрес в каждое поле «Тестовый URL», укажите идентификатор вашего проекта и нажмите «Сохранить» :

https://<project-id>.web.app/local-home/index.html

Далее нам нужно определить, как устройство Google Home должно обнаруживать локальные интеллектуальные устройства. Платформа Local Home поддерживает несколько протоколов для обнаружения устройств, включая mDNS, UPnP и широковещательную рассылку UDP. Для обнаружения умной стиральной машины вы будете использовать широковещательную рассылку UDP.

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

Добавьте обработчик IDENTIFIY.

SDK Local Home запускает обработчик 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 пользователя. После того, как Google найдет совпадение, устройство считается проверенным и готовым для локального выполнения.

Добавьте обработчик EXECUTE.

SDK Local Home запускает обработчик 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. Запустите умную стиральную машину.

Теперь пришло время проверить связь между вашим локальным приложением для выполнения заказов и умной стиральной машиной! Стартовый проект Codelab включает в себя виртуальную умную стиральную машину, написанную на Node.js, которая имитирует умную стиральную машину, которой пользователи могут управлять локально.

Настройте устройство

Необходимо настроить виртуальное устройство таким образом, чтобы оно использовало те же параметры UDP, которые вы применили к конфигурации сканирования для обнаружения устройств в консоли разработчика. Кроме того, необходимо указать виртуальному устройству, какой локальный идентификатор устройства следует сообщать и какой идентификатор проекта интеграции «облако-облако» следует использовать для событий отчета о состоянии при изменении состояния устройства.

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

Перейдите в каталог 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

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

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

На странице должен отобразиться список устройств, а URL-адрес вашего приложения должен появиться под названием вашего устройства Google Home.

Запустите инспектора

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

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

Протестируйте локальное выполнение заказов.

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

«Эй, Google, включи мою стиральную машину».

«Эй, Google, запусти мою стиральную машину».

«Эй, Google, останови мою стиральную машину».

Это должно заставить платформу отправить интент EXECUTE в ваше приложение TypeScript.

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

...
***** The washer is RUNNING *****
...
***** The washer is STOPPED *****

9. Поздравляем!

Поздравляем! Вы использовали Local Home SDK для интеграции локального выполнения заказов в облачную интеграцию.

Узнать больше

Вот ещё несколько вариантов, которые вы можете попробовать:

• Измените конфигурацию сканирования и убедитесь, что она работает. Например, попробуйте использовать другой UDP-порт или пакет обнаружения.
• Измените код виртуального интеллектуального устройства для работы на встроенном устройстве, например, Raspberry Pi, и используйте светодиоды или дисплей для визуализации текущего состояния.