Einem Zuhause neue Matter-Geräte hinzufügen

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

Xcode-Projektkonfiguration

   In der Beispiel-App für iOS implementiert   

Bevor Sie die Commissioning API implementieren, müssen Sie Ihren Xcode-Zielen die erforderlichen Funktionen, Berechtigungen und Info.plist-Eigenschaften hinzufügen:

Berechtigungen

Fügen Sie die folgenden Einträge in die .entitlements-Dateien des Hauptziels und der Erweiterung Ihrer App ein:

• Verwaltung von Thread-Netzwerkanmeldedaten:

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

  Wenn Sie diese Berechtigung in einem verteilten Build verwenden möchten, müssen Sie ein Antragsformular für die Berechtigung bei Apple einreichen. Apple verlangt, dass Sie Ihre Mitgliedschaft im Thread Group nachweisen und bestätigen, dass Ihr Thread Border Router (TBR) vom Thread Group zertifiziert ist.

• WLAN-Informationen:

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

• App-Gruppen: Fügen Sie eine freigegebene App-Gruppe hinzu, damit Ihre Haupt-App und die Matter Add Device Extension miteinander kommunizieren können (z. B. group.com.yourdomain.appgroupname). Diese Kennung wird vom Entwickler in der Apple Developer Console erstellt und registriert und muss mit der App-Gruppe übereinstimmen, die in den Zielfunktionen in Xcode konfiguriert ist. Das Google Home SDK verwendet diese Kennung in beiden Zielen, um den Inbetriebnahme-Status, die Fabric-Anmeldedaten und die Raumlisten mithilfe eines freigegebenen UserDefaults-Containers automatisch zu synchronisieren.

Schlüsselbundfreigabe (optional)

Wenn Ihre App-Erweiterung Anmeldedaten oder Zugriffstokens abrufen muss, die von der Haupt-App mit UserInfo.authorizationToken() gespeichert wurden, müssen Sie eine gemeinsame Schlüsselbund-Zugriffsgruppe für die Haupt-App und die App-Erweiterung in der plist-Datei für Berechtigungen konfigurieren:

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

Info.plist-Eigenschaften

Fügen Sie die folgenden Beschreibungsschlüssel in die Info.plist-Datei des Hauptziels Ihrer App ein:

• Beschreibung der Nutzung von Standortdaten:

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

• Bonjour-Dienste: Füge unter NSBonjourServices die Dienste hinzu, die für die lokale Matter- und Thread-Erkennung erforderlich sind:

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

• Beschreibung der Nutzung des lokalen Netzwerks: Fügen Sie den Schlüssel NSLocalNetworkUsageDescription mit einer Nachricht hinzu, in der die Berechtigungen für die Erkennung des lokalen Netzwerks erläutert werden.

Gerät in Betrieb nehmen

So nimmst du ein Matter-Gerät in Betrieb:

1. Benachrichtigen Sie den Home APIs iOS SDK, damit er sich auf die Inbetriebnahme von Matter mit structure.prepareForMatterCommissioning() vorbereiten kann. Mit diesem Befehl wird Folgendes ausgeführt:

   • Prüfen Sie, ob die Berechtigung gewährt wurde.
   • Der Hub muss online und erreichbar sein.
   • Achte darauf, dass keine andere Inbetriebnahme aktiv ist.

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

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

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

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

5. Konfigurieren Sie die Home-Instanz bei der Initialisierung so, dass die Gruppen-ID verwendet wird.

   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-App-Erweiterung Matter von Apple.

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

   Fügen Sie dem Erweiterungsziel mindestens das GoogleHomeMatterCommissionerSDK-Framework hinzu und überschreiben Sie drei Methoden, um die Google Home platform (GHP)HomeMatterCommissioner 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
       }
     }
   }