Adicionar novos dispositivos Matter a uma casa

As APIs Home para iOS usam um Matter hub para configurar um dispositivo em uma estrutura. Durante a configuração, o app envia um comando ao SDK e, em seguida, ao hub.

Configuração do projeto do Xcode

Antes de implementar a API Commissioning, adicione os recursos, direitos e propriedades Info.plist necessários aos destinos do Xcode:

Direitos

Inclua as seguintes entradas no destino principal do app e nos arquivos .entitlements da extensão:

  • Gerenciamento de credenciais da rede Thread:

    <key>com.apple.developer.networking.manage-thread-network-credentials</key>
<true/>

    Para usar esse direito em uma build distribuída, envie um formulário de solicitação de direitos à Apple. A Apple exige que você comprove a participação no Thread Group e verifique se o roteador de borda do Thread é certificado pelo Thread Group.

  • Informações da rede Wi-Fi:

    <key>com.apple.developer.networking.wifi-info</key>
<true/>

  • Grupos de apps: adicione um grupo de apps compartilhado para permitir que o app principal e a Matter extensão Add Device se comuniquem (por exemplo, group.com.yourdomain.appgroupname). Esse identificador é criado e registrado pelo desenvolvedor no Apple Developer Console e precisa corresponder ao grupo de apps configurado nos recursos de destino no Xcode. O SDK do Google Home usa esse identificador nos dois destinos para sincronizar automaticamente o estado de configuração, as credenciais de estrutura e as listas de ambientes usando um contêiner UserDefaults compartilhado.

Compartilhamento de chaves (opcional)

Se a extensão do app precisar recuperar credenciais ou tokens de acesso armazenados pelo app principal usando UserInfo.authorizationToken(), configure um grupo de acesso de chaves compartilhado para o app principal e os destinos de extensão do app nos arquivos plist de direitos:

<key>keychain-access-groups</key>
<array>
    <string>$(AppIdentifierPrefix)your.shared.keychain.group</string>
</array>

Propriedades do Info.plist

Inclua as seguintes chaves de descrição no Info.plist do destino principal do app:

  • Descrição do uso da localização:

    <key>NSLocationWhenInUseUsageDescription</key>
<string>Your custom message explaining why location access is needed to read the current Wi-Fi SSID</string>

  • Serviços Bonjour: Em NSBonjourServices, inclua os serviços necessários para a descoberta local de Matter e Thread:

    <key>NSBonjourServices</key>
<array>
    <string>_matter._tcp</string>
    <string>_matterc._udp</string>
    <string>_matterd._udp</string>
    <string>_meshcop._udp</string>
</array>

  • Descrição do uso da rede local: inclua a chave NSLocalNetworkUsageDescription com uma mensagem explicando as permissões de descoberta de rede local.

Configurar um dispositivo

Para configurar um dispositivo Matter:

  1. Notifique o Home APIs iOS SDK para se preparar para Matter solicitações de configuração com structure.prepareForMatterCommissioning(). Esse comando fará o seguinte:

    • Verificar se a permissão foi concedida.
    • Verificar se o hub está on-line e acessível.
    • Verificar se não há outra sessão de configuração ativa.
    do {
  try await structure.prepareForMatterCommissioning()
} catch {
  // Failed to prepare for Matter Commissioning
  return
}

  2. Crie uma solicitação com MatterAddDeviceRequest() para iniciar o fluxo de suporte da Apple Matter.

    let topology = MatterAddDeviceRequest.Topology(
  ecosystemName: "Google Home",
  homes: [MatterAddDeviceRequest.Home(displayName: structure.name)]
)

let request = MatterAddDeviceRequest(topology: topology)

  3. Execute a solicitação com perform(). Se ocorrer um erro, cancele a solicitação de configuração com structure.cancelMatterCommissioning().

    do {
  // Starting MatterAddDeviceRequest.
  try await request.perform()
  // Successfully completed MatterAddDeviceRequest.
  let commissionedDeviceIDs = try structure.completeMatterCommissioning()
  // Commissioned device IDs.
} catch let error {
  structure.cancelMatterCommissioning()
  // Failed to complete MatterAddDeviceRequest.
}

  4. Crie um App Group ID no Apple Developer Console para permitir que o app se comunique com a extensão MatterAddDevice ao configurar o dispositivo.

    Você também precisará atualizar o identificador do pacote de aplicativos e os perfis de provisionamento para usar esse ID do grupo.

  5. Ao inicializar, configure a instância Home para usar o identificador do grupo.

    func application(_ application: UIApplication, didFinishLaunchingWithOptions
launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
  Home.configure {
    $0.sharedAppGroup = "group.com.sample.app.commissioning"
  }

  return true
}

  6. Implemente a extensão do app Matter Matter para iOS da Apple.

    O exemplo de código mostra um exemplo de implementação de uma subclasse da API da Apple MatterAddDeviceExtensionRequestHandler.

    No mínimo, adicione o GoogleHomeMatterCommissionerSDK Framework ao destino da extensão e substitua três métodos para chamar as Google Home platformHomeMatterCommissioner APIs.

    • commissionDevice
    • rooms
    • configureDevice
    import MatterSupport
import GoogleHomeSDK
import OSLog

final class RequestHandler: MatterAddDeviceExtensionRequestHandler {
  // The App Group ID defined by the application to share information between the extension and main app.
  private static var appGroup = "group.com.sample.app.commissioning"

  ...

  // MARK: - Home API commissioning handlers

  /// Commissions a device to the Google Home ecosystem.
  /// - Parameters:
  ///   - home: The home that the device will be added to
  ///   - onboardingPayload: The payload to be sent to the Matter Commissioning SDK to commission the device.
  ///   - commissioningID: An identifier not used by the Home API SDK.
  override func commissionDevice(in home: MatterAddDeviceRequest.Home?, onboardingPayload: String, commissioningID: UUID) async throws {
    // Commission Matter device with payload.

    var onboardingPayloadForHub = onboardingPayload
    let homeMatterCommissioner = try HomeMatterCommissioner(appGroup: RequestHandler.appGroup)
    try await homeMatterCommissioner.commissionMatterDevice(
    onboardingPayload: onboardingPayloadForHub)
  }

  /// Obtains rooms from the Home Ecosystem to present to the user during the commissioning flow.
  /// - Parameter home: The home that the device will be added to.
  /// - Returns: A list of rooms if obtained from the Google Home ecosystem or an empty list if there was an error in getting them.
  override func rooms(in home: MatterAddDeviceRequest.Home?) async -> [MatterAddDeviceRequest.Room] {
    do {
      let homeMatterCommissioner = try HomeMatterCommissioner(appGroup: RequestHandler.appGroup)
      let fetchedRooms = try homeMatterCommissioner.fetchRooms()
      // Returning fetched rooms.
      return fetchedRooms
    } catch {
      // Failed to fetch rooms with error
      return []
    }
  }

  /// Pushes the device's configurations to the Google Home Ecosystem.
  /// - Parameters:
  ///   - name: The friendly name the user chose to set on the device.
  ///   - room: The room identifier that the user chose to put the device in.
  override func configureDevice(named name: String, in room: MatterAddDeviceRequest.Room?) async {
    // Configure Device name: room
    do {
      let homeMatterCommissioner = try HomeMatterCommissioner(appGroup: RequestHandler.appGroup)
      await homeMatterCommissioner.configureMatterDevice(
        deviceName: name, roomName: room?.displayName)
    } catch {
      // Configure Device failed with error
    }
  }
}