iOS এর জন্য ডিভাইস এবং ডিভাইস মেটাডেটা অ্যাক্সেস করুন

ডিভাইস এপিআইগুলো iOS-এর হোম এপিআই-এর মাধ্যমে অ্যাক্সেস করা যেতে পারে। আপনার অ্যাপে নিম্নলিখিত প্যাকেজগুলো ইম্পোর্ট করুন:

import GoogleHomeSDK
import GoogleHomeTypes

আরও তথ্যের জন্য, iOS-এর ডেটা মডেল দেখুন।

ত্রুটি পরিচালনা

Home API-এর কিছু মেথড HomeError থ্রো করে, তাই আমরা সুপারিশ করি যে আপনি ওই কলগুলোতে HomeError ধরার জন্য একটি do-catch ব্লক ব্যবহার করুন।

HomeError হ্যান্ডেল করার সময়, কী ভুল হয়েছে তা জানতে এর code এবং message ফিল্ডগুলো পরীক্ষা করুন।

যেকোনো অনিয়ন্ত্রিত ত্রুটির ফলে আপনার অ্যাপটি ক্র্যাশ করবে।

আরও তথ্যের জন্য, ত্রুটি পরিচালনা (Error handling ) দেখুন।

একটি উদাহরণের জন্য ‘কোনো ডিভাইসে কমান্ড পাঠান’ দেখুন।

নমুনা কল

ডিভাইসগুলির একটি তালিকা পান

Home অবজেক্টের একটি রেফারেন্স ব্যবহার করে, অ্যাক্সেসযোগ্য ডিভাইসগুলির একটি Query পেতে devices() কল করুন। Query এর batched() মেথডটি কল করুন, যা প্রতিটি ডিভাইসের মেটাডেটা পরিবর্তনের সাথে Home-এর বর্তমান অবস্থা প্রতিফলিত করে একটি Set প্রদান করে। অথবা উপলব্ধ ডিভাইসগুলির একটি স্ন্যাপশট পেতে 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 API-এর 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 প্রান্তবিন্দু) বিভক্ত করে।

এক্ষেত্রেও বৈশিষ্ট্যের সংঘর্ষের বিষয়টি বিবেচনা করা হয়, যদি কোনো ডিভাইসে দুই ধরনের ডিভাইস থাকে এবং উভয়টিরই একই বৈশিষ্ট্য থাকতে পারে। উদাহরণস্বরূপ, যদি একটি ডিভাইস একই সাথে স্পিকার এবং ডিমেবল লাইট হয়, তবে এর দুটি অন/অফ এবং দুটি লেভেল কন্ট্রোল বৈশিষ্ট্য থাকবে।

আরেক ধরনের ট্রেইট সংঘর্ষ ঘটতে পারে যখন কোনো ডিভাইসে একই নামের দুটি ট্রেইট থাকে। উদাহরণস্বরূপ, 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
}

ডিভাইসের অবস্থা পড়ুন

ডিভাইসের On/Off ট্রেইট থেকে 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)
    }
  }
}

হোম এপিআই-গুলিতে উপলব্ধ ট্রেইটগুলির সম্পূর্ণ তালিকার জন্য 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)
  }

হোম এপিআই-তে একাধিক ডিভাইস টাইপ রয়েছে যা একটি কোর ডিভাইস টাইপকে প্রতিনিধিত্ব করতে পারে। উদাহরণস্বরূপ, কোনো "লাইট" ডিভাইস টাইপ নেই। এর পরিবর্তে, চারটি ভিন্ন ডিভাইস টাইপ রয়েছে যা একটি লাইটকে প্রতিনিধিত্ব করতে পারে, যেমনটি পূর্ববর্তী উদাহরণে দেখানো হয়েছে। সুতরাং, একটি হোমের উচ্চ-স্তরের ডিভাইস টাইপের একটি পূর্ণাঙ্গ চিত্র পেতে হলে, একাধিক ডিভাইস টাইপ অন্তর্ভুক্ত করতে হবে।

হোম এপিআই-তে উপলব্ধ ডিভাইসের প্রকারভেদ এবং তাদের বৈশিষ্ট্যগুলির সম্পূর্ণ তালিকার জন্য 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 ডকুমেন্টেশন দেখুন।

ডিভাইস এবং বৈশিষ্ট্য মেটাডেটা

হোম এপিআই-এর ডিভাইস এবং বৈশিষ্ট্যগুলোর সাথে মেটাডেটা যুক্ত থাকে, যা একটি অ্যাপে ব্যবহারকারীর অভিজ্ঞতা পরিচালনায় সাহায্য করতে পারে।

হোম এপিআই-এর প্রতিটি ট্রেইটে একটি sourceConnectivity প্রপার্টি থাকে, যাতে ট্রেইটটির অনলাইন স্ট্যাটাস এবং লোকালিটি (লোকাল বা রিমোট রাউটিং) সম্পর্কিত তথ্য থাকে।

একটি ডিভাইসের প্রাথমিক ধরণটি পান

কিছু ডিভাইস হোম এপিআই (Home API)-এর মাধ্যমে একাধিক ডিভাইসের ধরন প্রদর্শন করতে পারে। ব্যবহারকারীরা যাতে তাদের ডিভাইসের জন্য অ্যাপে সঠিক বিকল্পগুলো (যেমন ডিভাইস নিয়ন্ত্রণ এবং প্রস্তাবিত অটোমেশন) দেখতে পান, তা নিশ্চিত করার জন্য ডিভাইসের ধরনটি সেটির প্রাথমিক ধরন কিনা তা যাচাই করে দেখা দরকারি।

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.")
  }
}

কোনো বৈশিষ্ট্য অনলাইন আছে কিনা তা পরীক্ষা করুন

একটি ট্রেইটের কানেক্টিভিটি পরীক্ষা করতে connectivityState প্রপার্টিটি পড়ুন:

let levelControlConnectivity =
  levelControlTrait.metadata.sourceConnectivity
  .connectivityState

কিছু বৈশিষ্ট্য, বিশেষ করে গুগল smart home বৈশিষ্ট্যগুলো, ডিভাইসে ইন্টারনেট সংযোগ না থাকলে অফলাইন দেখাতে পারে। এর কারণ হলো, এই বৈশিষ্ট্যগুলো ক্লাউড-ভিত্তিক এবং এগুলোতে লোকাল রাউটিং নেই।

একটি ডিভাইসের সংযোগ পরীক্ষা করুন

একটি ডিভাইসের কানেক্টিভিটি আসলে ডিভাইস টাইপ লেভেলে চেক করা হয়, কারণ কিছু ডিভাইস একাধিক ডিভাইস টাইপ সাপোর্ট করে। যে স্টেটটি রিটার্ন করা হয়, তা হলো সেই ডিভাইসের সমস্ত ট্রেইটের কানেক্টিভিটি স্টেটগুলোর একটি সমন্বয়।

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

ইন্টারনেট সংযোগ না থাকলে, বিভিন্ন ধরনের ডিভাইসের ক্ষেত্রে একটি partiallyOnline অবস্থা দেখা যেতে পারে। লোকাল রাউটিংয়ের কারণে Matter স্ট্যান্ডার্ড বৈশিষ্ট্যগুলো অনলাইন থাকতে পারে, কিন্তু ক্লাউড-ভিত্তিক বৈশিষ্ট্যগুলো অফলাইন থাকবে।

একটি ট্রেইটের নেটওয়ার্ক রাউটিং পরীক্ষা করুন

একটি ট্রেইটের অবস্থান হোম এপিআই-তেও পাওয়া যায়। dataSourceLocality নির্দেশ করে যে ট্রেইটটি দূরবর্তীভাবে (ক্লাউডের মাধ্যমে), স্থানীয়ভাবে (একটি স্থানীয় হাবের মাধ্যমে), নাকি পিয়ার-টু-পিয়ার (সরাসরি ডিভাইস থেকে ডিভাইসে, কোনো হাব ছাড়া) রাউট করা হচ্ছে।

উদাহরণস্বরূপ, কোনো অ্যাপ বুট হওয়ার সময় এবং ডিভাইস সংযোগের জন্য কোনো হাব বা সার্ভারে পৌঁছানোর আগেই যখন অবস্থানগত মান 'অনির্দিষ্ট unspecified হয়, তখন এমনটা হতে পারে। এই ডিভাইসগুলো নাগালের বাইরে থাকে এবং কমান্ড বা ইভেন্ট থেকে আসা ইন্টারঅ্যাকশন অনুরোধগুলো ব্যর্থ করে দেয়। এই ধরনের ডিভাইসগুলোকে কীভাবে পরিচালনা করতে হবে, তা নির্ধারণ করার দায়িত্ব ক্লায়েন্টের।

let levelControlLocality =
  levelControlTrait.metadata.sourceConnectivity
  .dataSourceLocality

একটি ডিভাইসের জন্য নেটওয়ার্ক রাউটিং পরীক্ষা করুন

কানেক্টিভিটির মতোই, লোকালিটিও ডিভাইস টাইপ লেভেলে যাচাই করা হয়। ফেরত আসা স্টেটটি হলো সেই ডিভাইসের সমস্ত ট্রেইটের লোকালিটির একটি সমন্বয়।

let lightLocality =
  dimmableLightDeviceType.metadata.sourceConnectivity.dataSourceLocality

partiallyOnline অনলাইন সংযোগের অনুরূপ পরিস্থিতিতে একটি mixed অবস্থা পরিলক্ষিত হতে পারে: যেখানে কিছু বৈশিষ্ট্য ক্লাউড-ভিত্তিক এবং অন্যগুলো স্থানীয়।

একটি ডিভাইসের নাম পরিবর্তন করুন

ডিভাইসের নাম পরিবর্তন করতে setName(_:) মেথডটি কল করুন:

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

কোনো ডিভাইসের নাম পরিবর্তন করার সময়, মূল HomeDevice স্ট্রাকচারটি অপরিবর্তিত থাকে এবং ফেরত আসা আপডেট করা HomeDevice অবজেক্টটিতে এই পরিবর্তন প্রতিফলিত হয়।

নাম ৬০ ইউনিকোড কোড পয়েন্ট (ক্যারেক্টার) সীমা অতিক্রম করলে তা সংক্ষিপ্ত করা হবে এবং কোনো ত্রুটি দেখানো হবে না। দীর্ঘ নাম পরিচালনার দায়িত্ব ডেভেলপারদের এবং উদাহরণস্বরূপ, তারা ব্যবহারকারীদের জানাতে চান কিনা যে নাম সংক্ষিপ্ত করা হবে, সেই সিদ্ধান্ত তারা নিতে পারেন।