Ajouter de nouveaux appareils Matter à une maison

Les API Home pour iOS utilisent un hub Matter pour mettre en service un appareil sur un tissu. Lors de la mise en service, l'application envoie une commande au SDK, puis au hub.

Pour mettre en service un appareil Matter:

  1. Informez le Home APIs iOS SDK pour qu'il se prépare aux demandes de mise en service Matter avec structure.prepareForMatterCommissioning(). Cette commande effectue les opérations suivantes:

    • Vérifiez que l'autorisation a été accordée.
    • Assurez-vous que le hub est en ligne et accessible.
    • Assurez-vous qu'aucune autre session de mise en service n'est en cours.
    do {
  try await structure.prepareForMatterCommissioning()
} catch {
  Logger.error("Failed to prepare for Matter Commissioning: \(error).")
  return
}

  2. Créez une requête avec MatterAddDeviceRequest() pour lancer le parcours d'assistance Matter d'Apple.

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

let request = MatterAddDeviceRequest(topology: topology)

  3. Exécutez la requête avec perform(). Si une erreur se produit, annulez la demande de mise en service avec 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. Créez un App Group ID dans la Apple Developer Console pour permettre à l'application de communiquer avec l'extension MatterAddDevice lors de la mise en service de l'appareil.

    Vous devrez également mettre à jour l'identifiant de votre bundle d'applications et les profils de provisionnement pour utiliser cet ID de groupe.

  5. Lors de l'initialisation, configurez l'instance Home pour qu'elle utilise l'identifiant de groupe.

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

  return true
}

  6. Implémentez l'extension d'application iOS Matter d'Apple.

    L'exemple de code montre comment implémenter une sous-classe de l'API MatterAddDeviceExtensionRequestHandler d'Apple.

    Ajoutez au moins le framework GoogleHomeMatterCommissionerSDK à la cible de l'extension et remplacez trois méthodes pour appeler les API 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).")
    }
  }
}