Menambahkan perangkat Matter baru ke rumah

Home API untuk iOS menggunakan hub Matter untuk mengaktifkan perangkat ke fabric. Selama aktivasi, aplikasi akan mengirim perintah ke SDK, lalu ke hub.

Konfigurasi project Xcode

Sebelum menerapkan Commissioning API, pastikan untuk menambahkan kemampuan, hak, dan properti Info.plist yang diperlukan ke target Xcode Anda:

Hak

Sertakan entri berikut dalam target aplikasi utama dan file .entitlements ekstensi:

  • Pengelolaan kredensial jaringan Thread:

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

    Untuk menggunakan hak ini dalam build terdistribusi, Anda harus mengirimkan formulir permintaan hak ke Apple. Apple mengharuskan Anda membuktikan keanggotaan di Thread Group dan memverifikasi bahwa Thread Border Router Anda disertifikasi oleh Thread Group.

  • Informasi Wi-Fi:

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

  • Grup aplikasi: Tambahkan grup aplikasi bersama untuk memungkinkan aplikasi utama dan Matter Ekstensi Tambah Perangkat berkomunikasi (misalnya, group.com.yourdomain.appgroupname). ID ini dibuat dan didaftarkan oleh developer di Konsol Apple Developer, dan harus cocok dengan Grup Aplikasi yang dikonfigurasi dalam kemampuan target di Xcode. Google Home SDK menggunakan ID ini di kedua target untuk otomatis menyinkronkan status aktivasi, kredensial fabric, dan daftar ruangan menggunakan penampung UserDefaults bersama.

Berbagi keychain (opsional)

Jika ekstensi aplikasi Anda perlu mengambil kredensial atau token akses yang disimpan oleh aplikasi utama menggunakan UserInfo.authorizationToken(), Anda harus mengonfigurasi grup akses keychain bersama untuk target aplikasi utama dan ekstensi aplikasi di plist haknya:

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

Properti Info.plist

Sertakan kunci deskripsi berikut di Info.plist target aplikasi utama Anda:

  • Deskripsi penggunaan lokasi:

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

  • Layanan Bonjour: Di bagian NSBonjourServices, sertakan layanan yang diperlukan untuk penemuan Matter dan Thread lokal:

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

  • Deskripsi penggunaan jaringan lokal: Sertakan kunci NSLocalNetworkUsageDescription dengan pesan yang menjelaskan izin penemuan jaringan lokal.

Mengaktifkan perangkat

Untuk mengaktifkan perangkat Matter:

  1. Beri tahu Home APIs iOS SDK untuk menyiapkan Matter permintaan aktivasi dengan structure.prepareForMatterCommissioning(). Perintah ini akan melakukan hal berikut:

    • Verifikasi bahwa izin telah diberikan.
    • Pastikan hub online dan dapat dijangkau.
    • Pastikan tidak ada sesi aktivasi aktif lainnya yang sedang berlangsung.
    do {
  try await structure.prepareForMatterCommissioning()
} catch {
  // Failed to prepare for Matter Commissioning
  return
}

  2. Buat permintaan dengan MatterAddDeviceRequest() untuk memulai alur dukungan Matter Apple.

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

let request = MatterAddDeviceRequest(topology: topology)

  3. Lakukan permintaan dengan perform(). Jika terjadi error, batalkan permintaan aktivasi dengan structure.cancelMatterCommissioning().

    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. Buat App Group ID di Konsol Apple Developer untuk memungkinkan aplikasi berkomunikasi dengan ekstensi MatterAddDevice saat mengaktifkan perangkat.

    Anda juga perlu memperbarui ID paket aplikasi dan profil provisi untuk menggunakan ID grup ini.

  5. Saat melakukan inisialisasi, konfigurasi instance Home untuk menggunakan ID grup.

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

  return true
}

  6. Implementasikan Ekstensi Aplikasi Matter iOS dari Apple.

    Kode contoh menunjukkan contoh penerapan subclass API Apple MatterAddDeviceExtensionRequestHandler.

    Minimal, tambahkan Framework GoogleHomeMatterCommissionerSDK ke target ekstensi dan ganti tiga metode untuk memanggil Google Home platformHomeMatterCommissioner API.

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