Einem Zuhause neue Matter-Geräte hinzufügen

Die Home APIs für iOS verwenden einen Matter Hub, um ein Gerät in einem Fabric in Betrieb zu nehmen. Während der Inbetriebnahme sendet die App einen Befehl an das SDK und dann an den Hub.

So nehmen Sie ein Matter Gerät in Betrieb:

1. Benachrichtigen Sie das Home APIs iOS SDK, dass es sich auf Matter Inbetriebnahmeanfragen mit structure.prepareForMatterCommissioning() vorbereiten soll. Mit diesem Befehl wird Folgendes ausgeführt:

   • Prüfen, ob die Berechtigung erteilt wurde
   • Prüfen, ob der Hub online und erreichbar ist
   • Prüfen, ob keine andere aktive Inbetriebnahmesitzung läuft

   do {
     try await structure.prepareForMatterCommissioning()
   } catch {
     // Failed to prepare for Matter Commissioning
     return
   }
   

2. Erstellen Sie mit MatterAddDeviceRequest() eine Anfrage, um den Support-Flow von Apple zu starten.Matter

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

3. Führen Sie die Anfrage mit perform() aus. Wenn ein Fehler auftritt, brechen Sie die Inbetriebnahmeanfrage mit structure.cancelMatterCommissioning() ab.

   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. Erstellen Sie in der Apple Developer Console eine App Group ID, damit die App bei der Inbetriebnahme des Geräts mit der Erweiterung MatterAddDevice kommunizieren kann.

   Außerdem müssen Sie die Bundle-ID Ihrer Anwendung und die Bereitstellungsprofile aktualisieren, um diese Gruppen-ID zu verwenden.

5. Konfigurieren Sie beim Initialisieren die Home-Instanz so, dass sie die Gruppen-ID verwendet.

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

6. Implementieren Sie die iOS Matter App Extension von Apple.

   Der Beispielcode zeigt ein Beispiel für die Implementierung einer Unterklasse der API von Apple MatterAddDeviceExtensionRequestHandler.

   Fügen Sie dem Erweiterungsziel mindestens das GoogleHomeMatterCommissionerSDK Framework hinzu und überschreiben Sie drei Methoden, um die Google Home platformHomeMatterCommissioner APIs aufzurufen.

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