Cómo agregar dispositivos Matter nuevos a una casa

Las APIs de Home para iOS usan un concentrador Matter para poner en servicio un dispositivo en una estructura. Durante la puesta en marcha, la app envía un comando al SDK y, luego, al concentrador.

Para poner en funcionamiento un dispositivo Matter, haz lo siguiente:

1. Notifica al Home APIs iOS SDK que se prepare para las solicitudes de puesta en marcha con structure.prepareForMatterCommissioning().Matter Este comando hará lo siguiente:

   • Verifica que se haya otorgado el permiso.
   • Asegúrate de que el concentrador esté en línea y se pueda acceder a él.
   • Asegúrate de que no haya otra sesión de puesta en marcha activa en curso.

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

2. Crea una solicitud con MatterAddDeviceRequest() para iniciar el flujo de asistencia de Matter de Apple.

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

3. Realiza la solicitud con perform(). Si se produce un error, cancela la solicitud de puesta en marcha con 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. Crea un App Group ID en Apple Developer Console para permitir que la app se comunique con la extensión MatterAddDevice cuando se ponga en servicio el dispositivo.

   También deberás actualizar el identificador del paquete de la aplicación y los perfiles de aprovisionamiento para usar este ID de grupo.

5. Cuando inicialices, configura la instancia de Home para que use el identificador de grupo.

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

6. Implementa la extensión de la app Matter para iOS de Apple.

   El código de muestra muestra un ejemplo de implementación de una subclase de la API de MatterAddDeviceExtensionRequestHandler de Apple.

   Como mínimo, agrega el framework GoogleHomeMatterCommissionerSDK al destino de la extensión y anula tres métodos para llamar a las APIs de 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).")
       }
     }
   }