किसी होम में नए Matter डिवाइस जोड़ना

iOS के लिए Home APIs, किसी डिवाइस को फ़ैब्रिक में शामिल करने के लिए Matter हब का इस्तेमाल करते हैं. कमीशनिंग के दौरान, ऐप्लिकेशन पहले एसडीके को और फिर हब को एक निर्देश भेजता है.

Xcode प्रोजेक्ट कॉन्फ़िगरेशन

   iOS के लिए सैंपल के तौर पर मिले ऐप्लिकेशन में लागू किया गया   

कमीशनिंग एपीआई को लागू करने से पहले, अपने Xcode टारगेट में ज़रूरी सुविधाएं, एनटाइटलमेंट, और Info.plist प्रॉपर्टी जोड़ना न भूलें:

दी जा रही सेवाएं

अपने मुख्य ऐप्लिकेशन टारगेट और एक्सटेंशन की .entitlements फ़ाइलों में, ये एंट्री शामिल करें:

  • Thread नेटवर्क के क्रेडेंशियल मैनेज करना:

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

    डिस्ट्रिब्यूट किए गए बिल्ड में इस एनटाइटलमेंट का इस्तेमाल करने के लिए, आपको Apple को एनटाइटलमेंट के अनुरोध वाला फ़ॉर्म सबमिट करना होगा. Apple के मुताबिक, आपको यह साबित करना होगा कि आप Thread Group के सदस्य हैं. साथ ही, आपको यह पुष्टि करनी होगी कि आपके Thread Border Router (TBR) को Thread Group से सर्टिफ़िकेट मिला है.

  • वाई-फ़ाई की जानकारी:

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

  • ऐप्लिकेशन ग्रुप: शेयर किया गया कोई ऐप्लिकेशन ग्रुप जोड़ें, ताकि आपका मुख्य ऐप्लिकेशन और Matter Add Device Extension आपस में कम्यूनिकेट कर सकें (उदाहरण के लिए, group.com.yourdomain.appgroupname). इस आइडेंटिफ़ायर को डेवलपर, अपने Apple Developer Console में बनाता और रजिस्टर करता है. साथ ही, यह Xcode में टारगेट की गई सुविधाओं में कॉन्फ़िगर किए गए ऐप्लिकेशन ग्रुप से मैच होना चाहिए. Google Home SDK, दोनों टारगेट में इस आइडेंटिफ़ायर का इस्तेमाल करता है. इससे, शेयर किए गए UserDefaults कंटेनर का इस्तेमाल करके, कमीशनिंग की स्थिति, फ़ैब्रिक क्रेडेंशियल, और कमरों की सूचियों को अपने-आप सिंक किया जाता है.

Keychain शेयर करना (ज़रूरी नहीं)

अगर आपके ऐप्लिकेशन एक्सटेंशन को UserInfo.authorizationToken() का इस्तेमाल करके, मुख्य ऐप्लिकेशन से सेव किए गए क्रेडेंशियल या ऐक्सेस टोकन वापस पाने की ज़रूरत है, तो आपको अपने मुख्य ऐप्लिकेशन और ऐप्लिकेशन एक्सटेंशन, दोनों के लिए शेयर किए गए कीचेन ऐक्सेस ग्रुप को कॉन्फ़िगर करना होगा. इसके लिए, आपको उनकी एनटाइटलमेंट plist में जाना होगा:

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

Info.plist प्रॉपर्टी

अपने मुख्य ऐप्लिकेशन टारगेट के Info.plist में, ब्यौरे की ये कुंजियां शामिल करें:

  • जगह की जानकारी के इस्तेमाल के बारे में जानकारी:

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

  • Bonjour सेवाएं: NSBonjourServices में जाकर, लोकल Matter और Thread की खोज के लिए ज़रूरी सेवाएं शामिल करें:

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

  • लोकल नेटवर्क के इस्तेमाल की जानकारी: NSLocalNetworkUsageDescription कुंजी के साथ एक मैसेज शामिल करें. इसमें लोकल नेटवर्क खोजने की अनुमतियों के बारे में बताया गया हो.

किसी डिवाइस को सेट अप करना

Matter डिवाइस को सेट अप करने के लिए:

  1. Home APIs iOS SDK को सूचना दें, ताकि वह structure.prepareForMatterCommissioning() के साथ Matter कमीशन करने के अनुरोधों के लिए तैयार हो सके. इस निर्देश से ये काम किए जा सकेंगे:

    • पुष्टि करें कि अनुमति दी गई है.
    • पक्का करें कि हब ऑनलाइन हो और उस तक पहुंचा जा सके.
    • पक्का करें कि कोई अन्य कमीशनिंग सेशन चालू न हो.
    do {
  try await structure.prepareForMatterCommissioning()
} catch {
  // Failed to prepare for Matter Commissioning
  return
}

  2. Apple की Matter सहायता टीम से संपर्क करने के लिए, MatterAddDeviceRequest() पर अनुरोध करें.

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

let request = MatterAddDeviceRequest(topology: topology)

  3. perform() के साथ अनुरोध करें. अगर कोई गड़बड़ी होती है, तो 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. Apple Developer Console में App Group ID बनाएं, ताकि डिवाइस को चालू करते समय ऐप्लिकेशन, MatterAddDevice एक्सटेंशन के साथ कम्यूनिकेट कर सके.

    इस ग्रुप आईडी का इस्तेमाल करने के लिए, आपको अपने ऐप्लिकेशन बंडल आइडेंटिफ़ायर और प्रोविज़निंग प्रोफ़ाइलों को भी अपडेट करना होगा.

  5. शुरू करते समय, ग्रुप आइडेंटिफ़ायर का इस्तेमाल करने के लिए, Home इंस्टेंस को कॉन्फ़िगर करें.

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

  return true
}

  6. Apple का iOS Matter ऐप्लिकेशन एक्सटेंशन लागू करें.

    सैंपल कोड में, Apple के MatterAddDeviceExtensionRequestHandler एपीआई की सबक्लास को लागू करने का उदाहरण दिखाया गया है.

    एक्सटेंशन टारगेट में कम से कम GoogleHomeMatterCommissionerSDK फ़्रेमवर्क जोड़ें. साथ ही, Google Home platform (GHP)HomeMatterCommissioner एपीआई को कॉल करने के लिए, तीन तरीकों को बदलें.

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