Criar um app para dispositivos móveis usando as APIs Home no iOS

1. Introdução

f154e30306882c74.png

O que são as APIs Home?

As APIs do Google Home oferecem um conjunto de bibliotecas para os desenvolvedores aproveitarem o ecossistema do Google Home. Com as APIs Home, os desenvolvedores podem criar apps que comissionam e controlam dispositivos de casa inteligente de maneira integrada.

3e11583c779a2cec.png

Este vídeo mostra um breve tutorial do app para dispositivos móveis que você vai criar. Assista ao vídeo enquanto faz o codelab.

Componentes das APIs Home

As APIs Home são compostas por:

  • APIs Device e Structure: interagem com a casa de um usuário. Os apps podem usar essas APIs para ler informações sobre dispositivos, ambientes e estruturas (por exemplo, ver a temperatura atual do termostato) e controlar dispositivos (por exemplo, mudar a temperatura programada do termostato).
  • API Commissioning: comissione (configure) novos dispositivos Matter no fabric com o mínimo de esforço.
  • API Automation: crie, exclua e consulte automações em execução na casa de um usuário.

Pré-requisitos

Tópicos de aprendizagem

  • Como criar um app iOS usando as APIs Home com as práticas recomendadas.
  • Como usar as APIs Device e Structure para representar e controlar uma casa inteligente.
  • Como usar a API Commissioning para adicionar dispositivos ao ecossistema Google Home.
  • Como usar a API Automation para criar uma automação básica.

2. Configurar sua casa

Preparar os dispositivos

O Google Home Playground oferece vários dispositivos de casa inteligente emulados e pré-criados. Ele é recomendado para explorar todo o potencial das APIs Home, principalmente se você tiver um número limitado de dispositivos em casa.

Siga as instruções para fazer login no Google Home Playground e concluir a vinculação de contas no app Google Home. Depois disso, você poderá ver os dispositivos na guia "Dispositivos" do app Google Home.

c892afce113abe8f.png

3. Etapas da configuração

Acessar o código do app de exemplo

Comece clonando o código-fonte do GitHub:

git clone https://github.com/google-home/google-home-api-sample-app-ios.git

O diretório de exemplo contém duas ramificações, start e finished, para este codelab.

  • start: o código inicial deste projeto, em que você fará mudanças para concluir o codelab.
  • finished: o código concluído deste codelab, usado para verificar seu trabalho.

Conhecer o código "inicial"

Comece este codelab mudando para a ramificação start do repositório clonado:

git checkout start

Essa ramificação contém o código inicial do projeto. Você vai modificar esse código ao longo do codelab para implementar a funcionalidade completa. O app de exemplo do codelab oferece uma estrutura básica criada em Swift para interagir com o SDK do iOS das APIs Home. Vamos conferir rapidamente os principais componentes do projeto start:

  • Main Entry (GoogleHomeAPISampleIOSApp): localizado em GoogleHomeAPISampleIOS/Main/GoogleHomeAPISampleIOS.swift, é o ponto de entrada principal do app. Ele configura e inicializa o SDK e configura a interface do usuário principal.
  • Core Views (View/):
    • MainView.swift: a visualização raiz após o lançamento, que contém o NavigationView principal. Ele seleciona a estrutura ativa do Google Home e mostra o StructureView correspondente.
    • StructureView.swift: mostra o conteúdo da estrutura selecionada no momento, usando guias para alternar entre uma grade de Dispositivos e a lista de Automações. Ele também oferece menus para adicionar quartos ou dispositivos.
    • DeviceView.swift: representa o bloco interativo de um único dispositivo na grade StructureView.
    • AutomationsView.swift: mostra a lista de automações atuais da estrutura e oferece navegação para criar ou ver detalhes da automação.
  • ViewModels (ViewModel/): essas classes gerenciam o estado e a lógica das visualizações.
    • AccountViewModel.swift: processa a conexão com o objeto Home e gerencia o estado de autenticação.
    • MainViewModel.swift: gerencia a lista de objetos Structure disponíveis e acompanha a estrutura selecionada.
    • StructureViewModel.swift: gerencia a exibição de quartos e objetos DeviceControl na estrutura selecionada.
    • AutomationList.swift, AutomationViewModel.swift e assim por diante: processa a busca, a exibição, a criação e o gerenciamento de automações.
  • Device Controls (ViewModel/Device/):
    • DeviceControl.swift: uma classe de base para representar dispositivos controláveis na interface.
    • Subclasses específicas (LightControl.swift, FanControl.swift, OnOffPlugInUnitControl.swift e assim por diante): implemente a lógica da interface, o controle do dispositivo e o mapeamento de estado para diferentes tipos de dispositivos com base nos traços deles.
    • DeviceControlFactory.swift: responsável por criar a subclasse DeviceControl adequada para um determinado HomeDevice.
  • Commissioning (Commissioning/):
    • CommissioningManager.swift: contém a lógica para gerenciar o fluxo de provisionamento do dispositivo Matter.
  • Utilities & UX (Utils/, UX/, Storage/): contém código auxiliar para elementos de UI (cores, dimensões), tratamento de erros, armazenamento de dados (SelectedStructureStorage.swift) e outros utilitários.

Ao longo deste codelab, você vai encontrar comentários como TODO ou blocos de código e alertas comentados no projeto start. Elas marcam as seções em que você vai adicionar ou remover marca de comentário do código para implementar a funcionalidade necessária, seguindo as etapas fornecidas.

Criar arquivos de configuração de implantação da Apple

Para configurar o App Attest, siga as instruções de criação de arquivos de configuração de implantação da Apple. Após a configuração, o app só pode ser implantado em um dispositivo real, não em um simulador.

Configurar a autenticação

Para receber o ID do cliente OAuth e ativar as APIs Home, primeiro faça login no Google Cloud e crie um projeto ou selecione um já existente. Em seguida, siga as etapas fornecidas para gerar o ID do cliente OAuth, ativar as APIs Home e adicionar sua conta à lista de permissões.

configurar o SDK

Consiga o SDK do iOS das APIs Home e configure-o seguindo as instruções de configuração fornecidas em Configurar o SDK. Substitua HOME_API_TODO_ADD_APP_GROUP pelo seu grupo de apps.

Criar e executar o projeto

Depois de criar e executar o projeto com a ramificação start, uma caixa de diálogo TODO e uma tela mostrando "Login obrigatório" vão aparecer. A interação das APIs Home será implementada nas seções a seguir.

bd56b7080037e38a.png 9c0f08a3f4197a77.png

Observação: para localizar o código que precisa ser modificado, pesquise no projeto o texto exibido na caixa de diálogo. Por exemplo, pesquise "TODO: initialize Home".

4. Inicialização

Inicializar o Home

Antes de usar qualquer uma das APIs Home para iOS, inicialize o Home no seu app. O Home é a entrada de nível superior para o SDK e fornece acesso a todas as entidades na estrutura do usuário. Ao solicitar todas as entidades de um tipo específico, a API retorna um objeto Query que permite escolher como receber os resultados. Em GoogleHomeAPISampleIOS/Accounts/AccountViewModel.swift, remova o comentário e o alerta em connect() para implementar a inicialização da casa.

  /// TODO: initialize Home
  /// Remove comments to initialize Home and handling permission.
  private func connect() {
    Task {
      do {
        self.home = try await Home.connect()
      } catch {
        Logger().error("Auth error: \(error).")
      }
    }
  }

Permissão para usar as APIs Home

A tela de consentimento vai aparecer quando você executar o app. Escolha a estrutura do Google Home e selecione a conta que está na lista de permissões do seu projeto do Google Cloud.

47310f458c0094d9.png 4a571dbd9979a88c.png e29c75891a3a67af.png

5. Dispositivos e estruturas

Receber salas e dispositivos

Em GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, remova o comentário e o alerta em getRoomsAndDevices() para receber os ambientes e dispositivos na estrutura selecionada com home.rooms() e home.devices(), respectivamente.

  /// TODO: get rooms and devices
  /// Remove comments to get the rooms and devices from home entry
  private func getRoomsAndDevices(){
    self.home.rooms().batched()
      .combineLatest(self.home.devices().batched())
      .receive(on: DispatchQueue.main)
      .catch { error in
        Logger().error("Failed to load rooms and devices: \(error)")
        return Just((Set<Room>(), Set<HomeDevice>()))
      }
      .map { [weak self] rooms, devices in
        guard let self = self else { return [] }
        self.hasLoaded = true
        return self.process(rooms: rooms, devices: devices)
      }
      /// receive from .map and .assign() to publisher entries
      .assign(to: &self.$entries)
  }

A função process() primeiro garante que os dispositivos estejam no mesmo ambiente antes de fazê-los interagir como HomeDevices usando DeviceControl e DeviceControlFactory.

4c677c4c294e67ca.png

Observação: se o dispositivo não estiver listado em DeviceControlFactory, ele vai aparecer como "Não compatível". Para saber mais sobre quais dispositivos são compatíveis, consulte a página Tipos de dispositivos compatíveis no iOS.

Interagir com um dispositivo

O plug-in outlet1 fica inativo ao tocar ou deslizar nos dispositivos. Para ativar a interação, localize o GoogleHomeAPISampleIOS/ViewModel/Device/OnOffPlugInUnitControl.swift e remova o comentário e o alerta na função primaryAction().

  /// TODO: primary action of OnOffPlug
  /// Toggles the plug; usually provided as the `action` callback on a Button.
  public override func primaryAction() {
    self.updateTileInfo(isBusy: true)
    Task { @MainActor [weak self] in
      guard
        let self = self,
        let onOffPluginUnitDeviceType = self.onOffPluginUnitDeviceType,
        let onOffTrait = onOffPluginUnitDeviceType.matterTraits.onOffTrait
      else { return }

      do {
        try await onOffTrait.toggle()
      } catch {
        Logger().error("Failed to to toggle OnOffPluginUnit on/off trait: \(error)")
        self.updateTileInfo(isBusy: false)
      }
    }
  }

A função primaryAction(), encontrada na classe OnOffPlugInUnitControl, alterna o estado de ativação/desativação de uma tomada inteligente ou qualquer dispositivo representado por OnOffPluginUnitDeviceType.

Outros exemplos de controle de dispositivo estão disponíveis em GoogleHomeAPISampleIOS/ViewModel/Device.

Criar um novo ambiente

A API Structure permite criar e excluir ambientes, além de transferir dispositivos entre eles.

Em GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, remova o comentário e o alerta em addRoom().

  /// TODO: add room
  /// Add a new room in a given structure.
  func addRoom(name: String, structure: Structure) {
    Task {
      do {
        // The view will be updated with the values from the devices publisher.
        _ = try await structure.createRoom(name: name)
      } catch {
        Logger().error("Failed to create room: \(error)")
      }
    }
  }

Para criar uma nova sala com o structure.createRoom(), navegue até o canto superior esquerdo e selecione o ícone "+" > Adicionar sala. Insira o novo nome da sala e clique em "Criar sala". A nova sala vai aparecer depois de alguns segundos.

b122ae6642b7da1c.png a45f785e1d51938e.png 7753b56cbdcff8d6.png

Mover o dispositivo para outro cômodo

Em GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, remova o comentário e o alerta em moveDevice().

  /// TODO: move device
  /// Move a device into a different room.
  func moveDevice(device deviceID: String, to roomID: String, structure: Structure) {
    Task {
      do {
        _ = try await structure.move(device: deviceID, to: roomID)
      } catch {
        Logger().error("Failed to move to room: \(error)")
      }
    }
  }

Para mudar o dispositivo de lugar com o structure.move(), pressione e mantenha pressionado, selecione "Mover para outro ambiente" e escolha o novo ambiente.

f9627592af44163d.png fd126fabb454f2bf.png 813e1e23e50cd9f6.png

Excluir uma sala vazia

Em GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, remova o comentário e o alerta em removeRoom().

  /// TODO: delete room
  /// Delete an empty room in a given structure.
  func removeRoom(id: String, structure: Structure) {
    Task {
      do {
        // The view will be updated with the values from the devices publisher.
        _ = try await structure.deleteRoom(id: id)
      } catch {
        Logger().error("Failed to remove room: \(error)")
      }
    }
  }

Para excluir uma sala vazia com structure.deleteRoom(), clique no ícone de lixeira à direita do nome da sala e confirme a ação. Só é possível excluir salas vazias.

4f129262ad67f564.png

Observação: mova o dispositivo de volta para criar um ambiente vazio.

6. Comissionamento

Observação: esta seção requer um hub do Google e um dispositivo Matter. Confira se o hub do Google na sua estrutura está on-line e acessível. Se você não tiver um dispositivo Matter, use o app Dispositivo virtual Matter.

Adicionar um dispositivo Matter

A API Commissioning permite que seu app adicione novos dispositivos Matter à casa do usuário e à Conta do Google. Isso oferece uma experiência de configuração integrada diretamente no seu app.

Em GoogleHomeAPISampleIOS/Commissioning/CommissioningManager.swift, remova o comentário e o alerta em addMatterDevice().

  /// TODO: add Matter Device
  /// Starts the Matter device commissioning flow to add the device to the user's home.
  /// - Parameters:
  ///   - structure: The structure to add the device to.
  ///   - add3PFabricFirst: Whether to add the device to a third party fabric first.
  public func addMatterDevice(to structure: Structure, add3PFabricFirst: Bool) {
    self.isCommissioning = true

    /// pass if it's 1p or 3p commissioning
    let userDefaults = UserDefaults(
      suiteName: CommissioningManager.appGroup)
    userDefaults?.set(
    add3PFabricFirst, forKey: CommissioningUserDefaultsKeys.shouldPerform3PFabricCommissioning)

    Task {
      do {
        try await structure.prepareForMatterCommissioning()
      } catch {
        Logger().error("Failed to prepare for Matter Commissioning: \(error).")
        self.isCommissioning = false
        return
      }

      // Prepare the Matter request by providing the ecosystem name and home to be added to.
      let topology = MatterAddDeviceRequest.Topology(
        ecosystemName: "Google Home",
        homes: [MatterAddDeviceRequest.Home(displayName: structure.name)]
      )
      let request = MatterAddDeviceRequest(topology: topology)

      do {
        Logger().info("Starting MatterAddDeviceRequest.")
        try await request.perform()
        Logger().info("Completed MatterAddDeviceRequest.")
        let commissionedDeviceIDs = try structure.completeMatterCommissioning()
        Logger().info("Commissioned device IDs: \(commissionedDeviceIDs).")
      } catch let error {
        structure.cancelMatterCommissioning()
        Logger().error("Failed to complete MatterAddDeviceRequest: \(error).")
      }

      self.isCommissioning = false
    }
  }

Para criar uma nova sala com o structure.prepareForMatterCommissioning(), acesse o canto superior esquerdo e selecione o ícone"+" > Adicionar dispositivo ao Google Fabric. Ele usa MatterAddDeviceRequest para adicionar o dispositivo Matter ao ambiente. Depois de selecionar o ambiente e o nome do dispositivo, ele vai aparecer na tela "Dispositivos".

adf6cbb531787aaf.png f002bd6320bc480d.png

7. Automação

Ver todas as automações na estrutura

Toque em Automações na barra de navegação inferior. Ele vai listar todas as automações na sua estrutura com structure.listAutomations().

cc6d50f72f812c24.png

Observação: se você não tiver nenhuma automação residencial configurada, a mensagem "Adicione uma automação para começar" vai aparecer.

Criar uma automação

Agora que você já conhece as APIs Device e Structure e sabe como adicionar um novo dispositivo, é hora de criar uma automação usando a API Automation.

Em GoogleHomeAPISampleIOS/ViewModel/Automation/AutomationsRepository.swift, remova o comentário, o alerta e a automação vazia em lightAutomation().

  /// TODO: create automation
  /// - Parameter devices: devices in current selected structure
  /// - Returns: the automation object to be created
  /// This automation will turn off the light after 5 seconds.
  public func lightAutomation(devices: Set<HomeDevice>) async throws -> any DraftAutomation {
    let light = devices.first { $0.name == "light2" }
    
    guard let light else {
      Logger().error("Unable to find light device with name light2")
      throw HomeError.notFound("No devices support OnOffLightDeviceType")
    }
    
    return automation(
      name: "Turn off light after 5 seconds",
      description:
        """
        Turns off light2 after it has been on for 5 seconds.
        """
    ) {
      let onOffStarter = starter(light, OnOffLightDeviceType.self, OnOffTrait.self)
      onOffStarter
      condition {
        onOffStarter.onOff.equals(true)
      }
      delay(for: Duration.seconds(5))
      action(light, OnOffLightDeviceType.self) {
        OnOffTrait.off()
      }
    }
  }

Para criar uma automação que desligue a luz cinco segundos depois de ser acesa, acesse a visualização de automação e clique no botão + Adicionar. Em seguida, selecione Desligar a iluminação após 5 segundos. Os detalhes da automação, incluindo o starter, o condition e o action, vão aparecer. Clique em Salvar para criar a automação por structure.createAutomation().

21c1f8ea2a29134b.png 4bd36f6ed9c5f6e9.png

Observação: as automações disponíveis dependem dos dispositivos na sua casa. Se não houver automações disponíveis, tente renomear o dispositivo de iluminação para "light2".

Volte à guia "Dispositivos" e acenda a iluminação chamada "light2". Ele será desligado automaticamente após cinco segundos.

Os componentes de uma automação são:

  • Ativação:é um evento que inicia a automação. Neste exemplo, a automação será iniciada quando houver uma mudança em OnOffTrait.
  • Condição: verifica se o dispositivo de ativação atende a requisitos específicos. Nesse caso, a automação seria executada se a iluminação estivesse acesa.
  • Ação:é a automação que você quer realizar, mas apenas se a ativação atender aos requisitos. Se as condições forem atendidas, a iluminação será apagada.

Para mais exemplos, consulte a página Exemplos de automações.

Excluir uma automação

O método structure.deleteAutomation() é invocado quando você desliza para a esquerda em uma automação e toca no ícone da lixeira para removê-la da sua estrutura.

dc678cd9e16f89a5.png

8. Parabéns

Parabéns! Você criou um app de casa inteligente básico usando as APIs Home para iOS.

O que você aprendeu:

  • Inicialização: conecte seu app ao ecossistema do Google Home usando Home.connect().
  • Permissões: autenticação e autorização de usuários processadas para acessar dados da casa.
  • Dispositivos e estruturas: ambientes e dispositivos buscados e mostrados usando home.rooms() e home.devices().
  • Controle de dispositivos: implementou a interação com dispositivos, como alternar o estado de um OnOffPluginUnitDeviceType chamando comandos nos traços dele.
  • Gerenciamento de estrutura: adicionamos a funcionalidade de criar novos ambientes (structure.createRoom()), mover dispositivos entre ambientes (structure.move()) e excluir ambientes vazios (structure.deleteRoom()).
  • Provisionamento: integramos o fluxo de provisionamento do SDK para adicionar novos dispositivos Matter (MatterAddDeviceRequest).
  • Automação: aprendemos a listar, criar (structure.createAutomation()) e excluir (structure.deleteAutomation()) automações em uma estrutura.

Agora você tem um entendimento básico de como aproveitar as APIs Home para criar experiências avançadas de controle de casa inteligente no iOS.

Próximas etapas:

  • Controle outros tipos de dispositivos fornecidos no app de exemplo (luzes, ventiladores, persianas etc.).
  • Saiba mais sobre os diferentes traços e comandos disponíveis para vários dispositivos.
  • Teste a criação de automações mais complexas usando diferentes ativações, condições e ações.
  • Consulte a documentação das APIs Home para mais recursos avançados e detalhes.

Muito bem!