Adicionar novos dispositivos Matter a uma casa

As APIs Home para iOS usam um hub Matter para comissionar um dispositivo em um fabric. Durante a comissionamento, o app envia um comando para o SDK e depois para o hub.

Para comissionar um dispositivo Matter:

  1. Notifique o Home APIs iOS SDK para se preparar para as solicitações de comissionamento Matter com structure.prepareForMatterCommissioning(). Esse comando vai fazer o seguinte:

    • Verifique se a permissão foi concedida.
    • Verifique se o hub está on-line e acessível.
    • Verifique se não há outra sessão de comissionamento ativa.
    do {
  try await structure.prepareForMatterCommissioning()
} catch {
  Logger.error("Failed to prepare for Matter Commissioning: \(error).")
  return
}

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

    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 comissionamento com structure.cancelMatterCommissioning().

    do {
  Logger.info("Starting MatterAddDeviceRequest.")
  try await request.perform()
  Logger.info("Successfully 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).")
}

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

    Você também vai precisar atualizar o identificador do pacote de aplicativos e os perfis de provisionamento para usar esse ID de 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 de app Matter para iOS da Apple.

    O código de exemplo mostra como implementar uma subclasse da API MatterAddDeviceExtensionRequestHandler da Apple.

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

    • commissionDevice
    • rooms
    • configureDevice
    import MatterSupport
import GoogleHomeMatterCommissionerSDK
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 {
    Logger.info("Commission Matter device with payload: '\(onboardingPayload)'.")

    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()
      Logger.info("Returning \(fetchedRooms.count) fetched rooms.")
      return fetchedRooms
    } catch {
      Logger.info("Failed to fetch rooms with error: \(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 {
    Logger.info("Configure Device name: '\(name)', room: \(room?.displayName ?? "").")
    do {
      let homeMatterCommissioner = try HomeMatterCommissioner(appGroup: RequestHandler.appGroup)
      await homeMatterCommissioner.configureMatterDevice(
        deviceName: name, roomName: room?.displayName)
    } catch {
      Logger.info("Configure Device failed with error: \(error).")
    }
  }
}