Implementar o app de fulfillment local

Para oferecer suporte ao fulfillment local, é preciso criar um app para lidar com essas intents de casa inteligente:

• IDENTIFY: oferece suporte à descoberta de dispositivos inteligentes controlados localmente. O O gerenciador de intents extrai dados que o dispositivo inteligente retorna durante a descoberta e a envia em resposta ao Google.
• EXECUTE: compatível com a execução de comandos.
• QUERY: oferece suporte à consulta do estado do dispositivo.
• REACHABLE_DEVICES: (opcional) oferece suporte à descoberta de objetos dispositivos finais atrás de um dispositivo hub ou ponte.

Este app é executado nos dispositivos Google Home ou Google Nest do usuário e conecta seu dispositivo inteligente a Google Assistente. Você pode criar o app usando TypeScript (preferencial) ou JavaScript.

O TypeScript é recomendado porque você pode aproveitar vinculações para garantir estaticamente que os dados retornados pelo aplicativo correspondam aos tipos que que a plataforma espera.

Para mais detalhes sobre a API, consulte a Referência da API Local Home SDK.

Os snippets a seguir mostram como inicializar o app de fulfillment local e anexar os gerenciadores.

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");
  });

Criar seu projeto

Para implantar seu app de fulfillment local, é preciso criar um pacote JavaScript para o código e todas as dependências dele.

Usar o projeto do app de fulfillment local inicializador para inicializar a estrutura do projeto apropriada com seu bundler preferido configuração do Terraform.

Modelos de projeto

Para selecionar a configuração do bundler, execute o comando npm init, conforme mostrado nas exemplos a seguir:

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

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

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

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

Realizar tarefas comuns no projeto

O projeto gerado é compatível com o seguinte npm scripts:

cd project-directory/
npm run build

cd project-directory/
npm run lint
npm run compile
npm test

cd project-directory/
npm run start

Implementar o gerenciador de IDENTIFICAÇÃO

O gerenciador IDENTIFY será acionado quando o dispositivo Google Home ou Google Nest for reinicializado e vê dispositivos locais não verificados (incluindo dispositivos finais conectados a um hub). O A plataforma do Google Home local vai procurar dispositivos locais usando as informações de configuração de verificação especificado anteriormente e chame o gerenciador IDENTIFY com os resultados da verificação.

O IdentifyRequest da plataforma Local Home contém os dados de verificação de um LocalIdentifiedDevice instância. Apenas uma instância device é preenchida, com base na configuração de verificação. que descobriu o dispositivo.

Se os resultados da verificação corresponderem ao seu dispositivo, o gerenciador IDENTIFY retornará uma IdentifyResponsePayload que inclui um objeto device com metadados de casa inteligente, como tipos, características e estado do relatório.

O Google estabelece uma associação de dispositivo se o verificationId da resposta IDENTIFY corresponde a uma das Valores otherDeviceIds retornados pela resposta SYNC.

Exemplo

Os snippets a seguir mostram como criar gerenciadores IDENTIFY para integrações de dispositivo autônomo e hub, respectivamente.

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;
  };

Identificar dispositivos por trás de um hub

Se o Google identificar um dispositivo hub, ele vai tratar o hub como o condutor aos dispositivos finais conectados ao hub e tentar verificá-los.

Para permitir que o Google confirme a presença de um dispositivo hub, siga estas etapas instruções para seu gerenciador IDENTIFY:

• Se a resposta SYNC informar os IDs dos dispositivos finais locais conectados ao hub, defina isProxy como true IdentifyResponsePayload
• Se a resposta SYNC não informar seu dispositivo hub, defina isLocalOnly como true em IdentifyResponsePayload
• O campo device.id contém o ID do dispositivo local para o próprio dispositivo hub.

Implementar o gerenciador REACHABLE_DEVICE (apenas integrações de hub)

A intent REACHABLE_DEVICES é enviada pelo Google para confirmar quais dispositivos finais. podem ser controladas localmente. Essa intent é acionada sempre que o Google executa um de descoberta (aproximadamente uma vez por minuto), desde que o hub seja detectado para estar on-line.

Implemente o gerenciador REACHABLE_DEVICES de maneira semelhante ao IDENTIFY. , com exceção de que ele precisa coletar IDs de dispositivo adicionais acessíveis pelo dispositivo de proxy local (ou seja, o hub). O O campo device.verificationId contém o ID do dispositivo local de um dispositivo final. que está conectado ao hub.

O ReachableDevicesRequest da plataforma Local Home contém uma instância do LocalIdentifiedDevice Por meio dessa instância, você pode obter o ID do dispositivo proxy, bem como os dados do os resultados da verificação.

Seu gerenciador REACHABLE_DEVICES deve retornar uma ReachableDevicesPayload que inclui um objeto devices que contém uma matriz de Valores verificationId que representam os dispositivos finais que o hub controla. O Os valores verificationId precisam corresponder a um dos otherDeviceIds do Resposta SYNC.

O snippet a seguir mostra como criar o 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;
  };

Implementar o gerenciador EXECUTE

O gerenciador EXECUTE no app processa comandos do usuário e usa o O SDK local do Google Home pode acessar seus dispositivos inteligentes com um protocolo.

A plataforma Local Home transmite o mesmo payload de entrada para o gerenciador EXECUTE. de acordo com a função EXECUTE para o fulfillment na nuvem. Da mesma forma, o gerenciador EXECUTE retorna dados de saída no mesmo formato do processamento da intent EXECUTE. Para simplificar a criação das respostas, use o Execute.Response.Builder que o SDK local do Google Home fornece.

Seu app não tem acesso direto ao endereço IP do dispositivo. Em vez disso, use o método CommandRequest para criar comandos com base em um destes protocolos: UDP, TCP ou HTTP. Em seguida, chame o método deviceManager.send() para enviar os comandos.

Ao segmentar comandos para dispositivos, use o ID do dispositivo (e os parâmetros do customData, se incluído) da resposta SYNC para se comunicar com o dispositivo.

Exemplo

O snippet de código a seguir mostra como criar o gerenciador 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());
  };

Implementar o gerenciador QUERY

O gerenciador QUERY no app processa solicitações do usuário e usa o O SDK local do Google Home informa o estado dos seus dispositivos inteligentes.

A plataforma Local Home transmite o mesmo payload de solicitação para a "QUERY". gerenciador para QUERY para o fulfillment na nuvem. Da mesma forma, o gerenciador QUERY retorna dados. no mesmo formato do processamento da intent QUERY.

Como enviar comandos para dispositivos atrás de um hub

Para controlar os dispositivos finais em um hub, talvez seja necessário enviar mais informações. no payload de comando específico do protocolo, enviado ao hub para que ele para identificar a que dispositivo o comando é direcionado. Em alguns casos, isso pode ser inferido diretamente do valor de device.id, mas, quando esse não for o caso, inclua esses dados extras como parte do campo customData.

Se você criou o app usando o TypeScript, faça a compilação para JavaScript. Você pode usar o sistema de módulos que preferir para escrever o código. Verifique se o destino é compatível com o navegador Chrome.