iOS के लिए डिवाइस और डिवाइस का मेटाडेटा ऐक्सेस करना

डिवाइस एपीआई को iOS के लिए Home APIs की मदद से ऐक्सेस किया जा सकता है. अपने ऐप्लिकेशन में ये पैकेज इंपोर्ट करें:

import GoogleHomeSDK
import GoogleHomeTypes

ज़्यादा जानकारी के लिए, iOS पर डेटा मॉडल देखें.

गड़बड़ी ठीक करना

Home APIs के कुछ तरीके HomeError दिखाते हैं. इसलिए, हमारा सुझाव है कि आप उन कॉल पर HomeError को पकड़ने के लिए, do-catch ब्लॉक का इस्तेमाल करें.

HomeError को हैंडल करते समय, इसके code और message फ़ील्ड देखें, ताकि आपको पता चल सके कि गड़बड़ी क्या है.

अगर गड़बड़ियों को ठीक नहीं किया जाता है, तो आपका ऐप्लिकेशन क्रैश हो जाएगा.

ज़्यादा जानकारी के लिए, गड़बड़ी ठीक करना लेख पढ़ें.

उदाहरण के लिए, किसी डिवाइस को निर्देश भेजना देखें.

सैंपल कॉल

डिवाइसों की सूची देखना

Home ऑब्जेक्ट के रेफ़रंस के साथ, devices() को शुरू करें, ताकि ऐक्सेस किए जा सकने वाले डिवाइसों की Query मिल सके. Query के batched() मेथड को कॉल करें. यह हर बार डिवाइस के मेटाडेटा में बदलाव होने पर, होम की मौजूदा स्थिति को दिखाने वाला सेट दिखाता है. इसके अलावा, उपलब्ध डिवाइसों की जानकारी पाने के लिए, Query.list() पर कॉल करें. यह एक आसान तरीका है, जो batched() स्ट्रीम की सदस्यता लेता है और पहली वैल्यू दिखाता है. Query.stream() एक ऐसी स्ट्रीम जनरेट करता है जो डिवाइस के मेटाडेटा में बदलाव होने पर नई वैल्यू दिखाती है. जैसे, डिवाइस का नाम, कमरा या स्ट्रक्चर. अंदरूनी तौर पर, यह batched() का इस्तेमाल करता है और सिर्फ़ बदली गई प्रॉपर्टी को दिखाता है.

// Get a list of all devices accessible to the user
let homeDevices = try await self.home.devices().list()

वहां से, हर डिवाइस की स्थिति को ऐक्सेस किया जा सकता है और डिवाइसों को निर्देश भेजे जा सकते हैं.

Home APIs के 1.8 वर्शन में, आपके पास यह विकल्प होता है कि एपीआई, कई हिस्सों वाले हर डिवाइस को एक डिवाइस के तौर पर दिखाए. इसके लिए, devices() तरीके के enableMultipartDevices पैरामीटर को true पर सेट करें. ज़्यादा जानकारी के लिए, iOS पर मल्टीपार्ट डिवाइस देखें.

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

किसी डिवाइस से जुड़ी डिवाइस टाइप की जानकारी पाने के लिए, डिवाइस की types प्रॉपर्टी पढ़ें. इससे DeviceTypeController मिलता है.

किसी खास तरह के डिवाइस के लिए अपडेट की सदस्यता लेने के लिए, DeviceTypeController.subscribe(_:) पर कॉल करें:

let devices = try await self.home.devices().list()
if let device = devices.first(where: { $0.id == myDeviceId }) {
  var receivedUpdate1 = false
  var receivedUpdate2 = false
  device.types.subscribe(OnOffLightDeviceType.self)
    .assertNoFailure()
    .sink { device in
      if !receivedUpdate1 {
        receivedUpdate1 = true
        Task {
          try await device.matterTraits.onOffTrait?.on()
        }
        return
      }
      if !receivedUpdate2 {
        receivedUpdate2 = true
        return
      }
      fatalError("Received unexpected update")
    }
}

अगर डिवाइस, बताए गए डिवाइस टाइप के साथ काम नहीं करता है, तो वह Empty Publisher दिखाता है, जो तुरंत पूरा हो जाता है.

अगर डिवाइस किसी खास तरह के डिवाइस के साथ काम करता है, तो get() को कॉल करके उस तरह के डिवाइस का हैंडल पाया जा सकता है:

if let device = devices.first(where: { $0.id == myDeviceId }) {
  let _ = await device.types.get(OnOffLightDeviceType.self)
}

अगर डिवाइस, बताए गए टाइप के साथ काम नहीं करता है, तो यह nil दिखाता है.

DeviceTypeCollection का Publisher पाने के लिए, DeviceTypeController.subscribeAll() पर कॉल करें. इस क्लास की मदद से, यह देखा जा सकता है कि डिवाइस किसी खास टाइप का है या नहीं:

if let device = devices.first(where: { $0.id == myDeviceId }) {
  device.types.subscribeAll()
    .assertNoFailure()
    .sink { types in
      let lightDeviceType = types[OnOffLightDeviceType.self]
      let fanDeviceType = types[FanDeviceType.self]
    }
}

डिवाइस टाइप की विशेषता पाना

डिवाइस टाइप, विशेषताओं को पढ़ने के लिए एंट्री पॉइंट होते हैं. ऐसा इसलिए, क्योंकि वे किसी डिवाइस को उसके काम करने वाले हिस्सों में बांटते हैं. जैसे, Matter में एंडपॉइंट.

अगर किसी डिवाइस में दो डिवाइस टाइप हैं और दोनों में एक जैसी विशेषता हो सकती है, तो वे विशेषता के टकराव को भी ध्यान में रखते हैं. उदाहरण के लिए, अगर कोई डिवाइस स्पीकर और डिम की जा सकने वाली लाइट, दोनों है, तो उसमें दो On/Off और दो Level Control ट्रेट होंगे.

ट्रेट कोलिज़न तब भी हो सकता है, जब किसी डिवाइस में एक ही नाम के दो ट्रेट हों. उदाहरण के लिए, onOff, स्टैंडर्ड OnOff ट्रेट के किसी इंस्टेंस या मैन्युफ़ैक्चरर के तय किए गए OnOff ट्रेट के किसी इंस्टेंस को रेफ़र कर सकता है. किसी भी तरह की गड़बड़ी से बचने के लिए, हर डिवाइस टाइप पर मौजूद दो ट्रेट कलेक्शन में से किसी एक का इस्तेमाल करके, ट्रेट को रेफ़रंस करें.

स्टैंडर्ड विशेषताओं के लिए, यानी कि Matter स्टैंडर्ड क्लस्टर से मिलती-जुलती विशेषताओं के लिए, matterTraits का इस्तेमाल करें. उदाहरण के लिए, रोशनी कम या ज़्यादा करने की सुविधा वाले डिवाइस के लिए, कोई खास विशेषता पाने के लिए:

if let dimmableLightDeviceType =
  await device.types.get(DimmableLightDeviceType.self)
{
  // Accessing standard trait on the type.
  let levelControlTrait =
    dimmableLightDeviceType.matterTraits.levelControlTrait.self
}

Google की विशेषताओं के लिए, googleTraits का इस्तेमाल करें:

if let doorbellDeviceType = await device.types.get(GoogleDoorbellDeviceType.self) {
  // Accessing Google trait on the type.
  let doorbellPressTrait =
    doorbellDeviceType.traits[Google.DoorbellPressTrait.self]
}

मैन्युफ़ैक्चरर के हिसाब से तय की गई किसी ख़ासियत को ऐक्सेस करने के लिए, traits प्रॉपर्टी का इस्तेमाल करके उसे रेफ़र करें. हालांकि, इसके लिए मैन्युफ़ैक्चरर के पैकेज का नाम पहले डालें:

let deviceType = await device1?.types.get(OnOffLightDeviceType.self)
// Accessing custom trait on the type.
if let spinnerTrait = deviceType?.traits[ExampleOrganization.SpinnerTrait.self] {
  let rpmVal = spinnerTrait.attributes.rpm
}

डिवाइस की स्थिति देखना

डिवाइस की चालू/बंद करने की विशेषता से, OnOff एट्रिब्यूट की जाँच करने का यह उदाहरण देखें:

let lightDevices = devices.filter {
  $0.types.contains(OnOffLightDeviceType.self)
}
let light1 = lightDevices.first
let lightDeviceTypeOptional = await light1?.types.get(OnOffLightDeviceType.self)
if let onOffTrait = lightDeviceTypeOptional?.matterTraits.onOffTrait {
  let onOffVal = onOffTrait.attributes.onOff
}

किसी खास विशेषता वाले डिवाइसों की सूची पाना

किसी खास विशेषता वाले डिवाइसों की सूची पाने के लिए, आपको डिवाइसों, हर डिवाइस के टाइप, और हर डिवाइस टाइप की विशेषताओं को बार-बार देखना होगा. उदाहरण के लिए, होम में मौजूद उन सभी डिवाइसों की सूची पाने के लिए जिनमें चालू/बंद करने की सुविधा है:

// Get all light devices that support levelControl
var levelControlDevices: [HomeDevice] = []
let allDevices = try await home.devices().list()
for device in allDevices {
  if let deviceType = await device.types.get(OnOffLightDeviceType.self) {
    if deviceType.traits.contains(Matter.LevelControlTrait.self) {
      levelControlDevices.append(device)
    }
  }
}

Home APIs में उपलब्ध सभी ट्रेट की सूची देखने के लिए, iOS पर ट्रेट इंडेक्स देखें.

एक जैसे डिवाइस टाइप वाले डिवाइसों की सूची पाना

घर की सभी लाइटों को दिखाने वाले डिवाइसों की सूची पाने के लिए:

// Get a list of devices with similar device types (lights)
let lightDevices =
  try await self.home.devices().list().compactMap {
    $0.types.contains(DimmableLightDeviceType.self)
      || $0.types.contains(OnOffLightDeviceType.self)
      || $0.types.contains(ColorTemperatureLightDeviceType.self)
      || $0.types.contains(ExtendedColorLightDeviceType.self)
  }

Home APIs में कई तरह के डिवाइस टाइप मौजूद हैं, जो किसी मुख्य डिवाइस टाइप को दिखा सकते हैं. उदाहरण के लिए, "लाइट" नाम का कोई डिवाइस टाइप नहीं है. इसके बजाय, चार अलग-अलग तरह के डिवाइस हैं जो लाइट को दिखा सकते हैं. जैसा कि पिछले उदाहरण में दिखाया गया है. इसलिए, घर में मौजूद डिवाइसों के टाइप की पूरी जानकारी पाने के लिए, डिवाइस के कई टाइप शामिल किए जाने चाहिए.

Home APIs में उपलब्ध डिवाइस टाइप और उनकी विशेषताओं की पूरी सूची देखने के लिए, iOS पर इस्तेमाल किए जा सकने वाले डिवाइस टाइप देखें.

किसी डिवाइस के लिए वेंडर का नाम, वेंडर आईडी या प्रॉडक्ट आईडी पता करना

BasicInformationTrait ट्रेट में, किसी डिवाइस के वेंडर आईडी, प्रॉडक्ट आईडी, प्रॉडक्ट का नाम, और सीरियल नंबर जैसी जानकारी शामिल होती है:

guard
  let vendorName =
    basicInfoTrait.attributes.vendorName
else {
  fatalError("Failed to get vendorName")
}
guard
  let vendorID =
    basicInfoTrait.attributes.vendorID
else {
  fatalError("Failed to get vendorID")
}
guard
  let productID =
    basicInfoTrait.attributes.productID
else {
  fatalError("Failed to get productID")
}

डिवाइस मैन्युफ़ैक्चरर के लिए, क्लाउड-टू-क्लाउड डिवाइस की पहचान करना

अगर आप डिवाइस बनाने वाली कंपनी हैं और Cloud-to-cloud डिवाइस बनाती हैं, तो BasicInformation ट्रेट की मदद से अपने Cloud-to-cloud डिवाइसों की पहचान करने के लिए, इन स्ट्रिंग फ़ील्ड को उनके SYNC रिस्पॉन्स में शामिल किया जा सकता है:

• Connectivity Standards Alliance (Alliance) की ओर से जारी किया गया वेंडर आईडी: "matterOriginalVendorId": "0xfff1",

• प्रॉडक्ट आइडेंटिफ़ायर, जो किसी वेंडर के प्रॉडक्ट की खास तौर पर पहचान करता है: "matterOriginalProductId": "0x1234",

• डिवाइस के लिए एक यूनीक आइडेंटिफ़ायर, जिसे मैन्युफ़ैक्चरर के हिसाब से बनाया जाता है: "matterUniqueId": "matter-device-id",

इन स्ट्रिंग फ़ील्ड को डालते समय, अपने Matter वेंडर और प्रॉडक्ट आईडी का इस्तेमाल करें, अगर आपके पास ये हैं. अगर आप Alliance के सदस्य नहीं हैं और आपको ये आईडी असाइन नहीं किए गए हैं, तो matterOriginalVendorId और matterOriginalProductId फ़ील्ड को खाली छोड़ा जा सकता है. साथ ही, आइडेंटिफ़ायर के तौर पर matterUniqueId दिया जा सकता है.

SYNC के जवाब के उदाहरण में, इन फ़ील्ड का इस्तेमाल दिखाया गया है:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "456",
        "type": "action.devices.types.LIGHT",
        "traits": [
          "action.devices.traits.OnOff",
          "action.devices.traits.Brightness",
          "action.devices.traits.ColorSetting",
        ],
        "willReportState": true,
        "deviceInfo": { ... },
        "matterOriginalVendorId": "0xfff1",
        "matterOriginalProductId": "0x1234",
        "matterUniqueId": "matter-device-id",
        "otherDeviceIds": [
          {
            "deviceId": "local-device-id",
          }
        ]
      }
    ]
  }
}

ज़्यादा जानकारी के लिए, Cloud-to-cloud SYNC दस्तावेज़ देखें.

डिवाइस और ट्रेट का मेटाडेटा

Home APIs में मौजूद डिवाइसों और उनकी विशेषताओं से जुड़ा मेटाडेटा होता है. इससे किसी ऐप्लिकेशन में उपयोगकर्ता अनुभव को मैनेज करने में मदद मिल सकती है.

Home APIs में मौजूद हर trait में एक sourceConnectivity प्रॉपर्टी होती है. इसमें trait के ऑनलाइन स्टेटस और लोकैलिटी (लोकल या रिमोट रूटिंग) की जानकारी होती है.

किसी डिवाइस के मुख्य टाइप की जानकारी पाना

कुछ डिवाइसों में, Home APIs के ज़रिए कई तरह के डिवाइसों की जानकारी दिख सकती है. यह पक्का करने के लिए कि उपयोगकर्ताओं को किसी ऐप्लिकेशन में उनके डिवाइसों के लिए सही विकल्प दिखें (जैसे, डिवाइस कंट्रोल और सुझाए गए ऑटोमेशन), यह देखना ज़रूरी है कि डिवाइस का टाइप, डिवाइस का मुख्य टाइप है या नहीं.

if let deviceType =
  await device?.types.get(HumiditySensorDeviceType.self)
{
  if deviceType.metadata.isPrimaryType {
    print("Humidity Sensor is the primary type on this device.")
  } else {
    print("Humidity Sensor isn't the primary type on this device.")
  }
}

यह देखना कि कोई trait ऑनलाइन है या नहीं

किसी ट्रेट की कनेक्टिविटी की जांच करने के लिए, connectivityState प्रॉपर्टी को पढ़ें:

let levelControlConnectivity =
  levelControlTrait.metadata.sourceConnectivity
  .connectivityState

अगर डिवाइस में इंटरनेट कनेक्टिविटी नहीं है, तो कुछ विशेषताएं ऑफ़लाइन दिख सकती हैं. आम तौर पर, Google smart home की विशेषताएं ऑफ़लाइन दिखती हैं. ऐसा इसलिए है, क्योंकि ये ट्रेट क्लाउड-आधारित होते हैं और इनमें लोकल रूटिंग की सुविधा नहीं होती.

किसी डिवाइस के लिए कनेक्टिविटी की जांच करना

किसी डिवाइस की कनेक्टिविटी की जांच, डिवाइस टाइप के लेवल पर की जाती है. ऐसा इसलिए, क्योंकि कुछ डिवाइसों पर कई तरह के डिवाइस टाइप काम करते हैं. डिवाइस की स्थिति, उस डिवाइस पर मौजूद सभी विशेषताओं के लिए कनेक्टिविटी की स्थितियों का कॉम्बिनेशन होती है.

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

इंटरनेट कनेक्शन न होने पर, अलग-अलग तरह के डिवाइसों के मामले में partiallyOnline की स्थिति देखी जा सकती है. लोकल रूटिंग की वजह से, Matter के स्टैंडर्ड ट्रेट अब भी ऑनलाइन हो सकते हैं. हालांकि, क्लाउड-आधारित ट्रेट ऑफ़लाइन होंगे.

डिवाइस का आईपी पता पाना

डिवाइस का आईपी पता ढूंढने के लिए, GeneralDiagnosticsTrait के networkInterfaces एट्रिब्यूट का इस्तेमाल करें. पते, Data ऑब्जेक्ट के तौर पर दिखाए जाते हैं. इन्हें Network फ़्रेमवर्क का इस्तेमाल करके, स्टैंडर्ड IPv4 या IPv6 स्ट्रिंग में फ़ॉर्मैट किया जा सकता है:

func getIpAddresses(trait: Matter.GeneralDiagnosticsTrait) -> [String] {
  let interfaces = trait.attributes.networkInterfaces ?? []
  var ipAddresses: [String] = []

  for interface in interfaces {
    for data in interface.iPv4Addresses {
      if let ipv4 = IPv4Address(data) {
        ipAddresses.append(String(describing: ipv4))
      }
    }
    for data in interface.iPv6Addresses {
      if let ipv6 = IPv6Address(data) {
        ipAddresses.append(String(describing: ipv6))
      }
    }
  }

  return ipAddresses
}

किसी ट्रेट की नेटवर्क रूटिंग देखना

किसी trait के लिए locality की जानकारी, Home APIs में भी उपलब्ध होती है. dataSourceLocality से पता चलता है कि विशेषता को रिमोटली (क्लाउड के ज़रिए), स्थानीय तौर पर (स्थानीय हब के ज़रिए) या पीयर-टू-पीयर (सीधे डिवाइस से डिवाइस पर, कोई हब नहीं) रूट किया गया है या नहीं.

इलाके की जानकारी न होने पर, वैल्यू unspecified हो सकती है. उदाहरण के लिए, जब कोई ऐप्लिकेशन बूट हो रहा हो और डिवाइस कनेक्टिविटी के लिए, अब तक किसी हब या सर्वर तक न पहुंचा हो. इन डिवाइसों को ऐक्सेस नहीं किया जा सकता. साथ ही, ये निर्देशों या इवेंट से इंटरैक्शन के अनुरोधों को पूरा नहीं कर पाएंगे. यह क्लाइंट पर निर्भर करता है कि वह ऐसे डिवाइसों को कैसे मैनेज करे.

let levelControlLocality =
  levelControlTrait.metadata.sourceConnectivity
  .dataSourceLocality

किसी डिवाइस के लिए नेटवर्क रूटिंग की जांच करना

कनेक्टिविटी की तरह ही, डिवाइस के टाइप के लेवल पर स्थानीयता की जांच की जाती है. स्टेटस के तौर पर, उस डिवाइस पर मौजूद सभी विशेषताओं की लोकैलिटी का कॉम्बिनेशन दिखता है.

let lightLocality =
  dimmableLightDeviceType.metadata.sourceConnectivity.dataSourceLocality

mixed की स्थिति, partiallyOnline कनेक्टिविटी की तरह ही दिख सकती है: कुछ सुविधाएं क्लाउड-आधारित होती हैं, जबकि कुछ सुविधाएं स्थानीय होती हैं.

किसी डिवाइस का नाम बदलना

किसी डिवाइस का नाम बदलने के लिए, setName(_:) तरीके को कॉल करें:

let updatedDevice = try await theDevice.setName("new device name")

किसी डिवाइस का नाम बदलने पर, ओरिजनल HomeDevice स्ट्रक्चर में कोई बदलाव नहीं होता. हालांकि, अपडेट किए गए HomeDevice ऑब्जेक्ट में यह बदलाव दिखता है.

अगर नाम 60 यूनिकोड कोड पॉइंट (वर्ण) की सीमा से ज़्यादा हैं, तो उन्हें छोटा कर दिया जाएगा. साथ ही, कोई गड़बड़ी नहीं दिखाई जाएगी. लंबे नामों को मैनेज करने की ज़िम्मेदारी डेवलपर की होती है. उदाहरण के लिए, वे यह तय कर सकते हैं कि उपयोगकर्ताओं को यह बताना है या नहीं कि उनके नाम छोटे कर दिए जाएंगे.

यह देखना कि कोई डिवाइस किस ग्रुप का सदस्य है

कोई फ़िज़िकल डिवाइस, एक या उससे ज़्यादा डिवाइस ग्रुप का हिस्सा हो सकता है. यह देखने के लिए कि कोई डिवाइस किन ग्रुप में शामिल है, डिवाइस पर GroupMembershipTrait देखें:

if let trait = await device.traits.get(Google.GroupMembershipTrait.self) {
  for groupId in trait.attributes.groupObjectIdsArray {
    print("Device belongs to group: \(groupId)")
  }
}

DeviceGroup के साथ काम करने वाले डिवाइस टाइप की जांच करने और ग्रुप को एक इकाई के तौर पर निर्देश भेजने के लिए, डिवाइस ग्रुप को कंट्रोल करना लेख पढ़ें.