Android-এর জন্য ডিভাইস ও ডিভাইসের মেটাডেটা অ্যাক্সেস করুন

Android-এর জন্য Home API-এর মাধ্যমে ডিভাইস API অ্যাক্সেস করা যেতে পারে। আপনার অ্যাপে এইসব প্যাকেজ ইমপোর্ট করুন:

import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.Id

Device API-এর সাথে নির্দিষ্ট ডিভাইসের ধরন বা বৈশিষ্ট্য ব্যবহার করতে, সেগুলি আলাদাভাবে ইমপোর্ট করতে হবে।

যেমন, Matter চালু/বন্ধ করার বৈশিষ্ট্য এবং চালু/বন্ধ করার প্লাগ-ইন ইউনিট ডিভাইসের ধরন ব্যবহার করতে, আপনার অ্যাপ্লিকেশনে নিম্নলিখিত প্যাকেজ ইমপোর্ট করুন:

import com.google.home.matter.standard.OnOff
import com.google.home.matter.standard.OnOffPluginUnitDevice

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

সমস্যা ম্যানেজ করা

Home API-এর যেকোনও পদ্ধতি HomeException থ্রো করতে পারে, তাই আমরা সাজেস্ট করি যে আপনি সব কলে HomeException ক্যাচ করতে try-catch ব্লক ব্যবহার করুন।

HomeException হ্যান্ডেল করার সময়, কী সমস্যা হয়েছে তা জানতে এর error.code এবং error.message ফিল্ড চেক করুন। এছাড়াও, সাব-এরর কোড থাকতে পারে, তাই getSubErrorCodes() পদ্ধতি কল করুন এবং ফলাফল চেক করুন।

কোনও হ্যান্ডেল না করা ব্যতিক্রমের ফলে আপনার অ্যাপ ক্র্যাশ করবে।

আরও তথ্যের জন্য, সমস্যা সমাধান দেখুন।

উদাহরণ দেখতে ডিভাইসে কমান্ড পাঠান বিকল্প দেখুন।

স্যাম্পেল কল

ডিভাইসের তালিকা পান

Structure ইনস্ট্যান্সের রেফারেন্স পাওয়ার পরে, devices() কল সেই স্ট্রাকচার থেকে আপনার অ্যাক্সেসযোগ্য ডিভাইসের Flow রিটার্ন করে:

// Get a flow of all devices accessible to the user
val allDevicesFlow: HomeObjectsFlow<HomeDevice> = home.devices()

// Calling list() on a HomeObjectsFlow returns the first Set of elements.
val allDevices: Set<HomeDevice> = allDevicesFlow.list()

সেখান থেকে, আপনি প্রতিটি ডিভাইসের স্ট্যাটাস অ্যাক্সেস করতে এবং ডিভাইসে কমান্ড পাঠাতে পারবেন।

Home API-এর 1.8 রিলিজের সাথে, আপনার কাছে devices() পদ্ধতির enableMultipartDevices প্যারামিটার true-এ সেট করে প্রতিটি মাল্টিপার্ট ডিভাইসকে একটি একক ডিভাইস হিসেবে API-এর মাধ্যমে দেখানোর বিকল্প রয়েছে। আরও তথ্যের জন্য Android-এ মাল্টিপার্ট ডিভাইস দেখুন।

ডিভাইসের স্ট্যাটাস রিড করা

ডিভাইসের চালু/বন্ধ করার বৈশিষ্ট্য থেকে OnOff অ্যাট্রিবিউট চেক করার উদাহরণ দেখুন। Home API-এর ট্রেট ডেটা মডেল ব্যবহার করে, যেখানে এই ট্রেটকে OnOff হিসেবে শনাক্ত করা হয়, আপনি ডিভাইসের প্রকারের standardTraits ক্লাসের মাধ্যমে ট্রেট ডেটা ফিরিয়ে আনতে পারবেন:

// Assuming we have a device.
val deviceFlow = home.devices().itemFlow(myDeviceId)

val device = deviceFlow.first()

// Get a flow of a standard trait on the type. distinctUntilChanged() is needed to only trigger
// on the specific trait changes and not the whole type.
val onOffTraitFlow: Flow<OnOff?> =
  device.type(DimmableLightDevice).map { it.standardTraits.onOff }.distinctUntilChanged()

val onOffTrait: OnOff = onOffTraitFlow.first()!!

Kotlin ফ্লো ফাংশন সম্পর্কে আরও জানতে distinctUntilChanged দেখুন।

কোনও ট্রেট সাবস্ক্রিপশনে স্ট্যাটাস বাতিল করুন

TraitStateInvalidation ইন্টারফেস টার্গেট ডিভাইসে সাবস্ক্রিপশনের মাধ্যমে পাওয়া স্ট্যাটাস ভুলভাবে রিপোর্ট করা হলে, সেটি বাতিল করার সুবিধা প্রদান করে। "C" কোয়ালিটি সহ Matter বৈশিষ্ট্যে অ্যাট্রিবিউট ব্যবহার করা অথবা ডিভাইস ইমপ্লিমেন্টেশনের কারণে অপ্রত্যাশিতভাবে সমস্যা হওয়ার মতো পরিস্থিতিতে স্ট্যাটাস সঠিকভাবে রিপোর্ট নাও করা হতে পারে।

এই API বর্তমান ট্রেইট স্টেটকে জোরপূর্বক রিড করে এবং আগে থেকে থাকা ট্রেইট ফ্লোয়ের মাধ্যমে ফলাফল দেখায়।

বৈশিষ্ট্যটি পান, তারপর বৈশিষ্ট্যটিতে একটি forceRead চালান:

val onOffTrait = device.?type(DimmableLightDevice)?.map{it.trait(OnOff)}.first()
onOffTrait.forceRead()

ডিভাইসের ধরন সংক্রান্ত বৈশিষ্ট্যের তালিকা পান

ডিভাইসের ধরনকে বৈশিষ্ট্য পড়ার এন্ট্রি পয়েন্ট হিসেবে ব্যবহার করা উচিত, কারণ সেগুলি ডিভাইসকে তার ফাংশনাল অংশে (যেমন Matter-এ এন্ডপয়েন্ট) বিভক্ত করে।

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

ডিম করা যায় এমন লাইট ডিভাইসের ধরনের জন্য উপলভ্য বৈশিষ্ট্যের তালিকা পেতে:

// Get all types available on this device. Requires the types to be part of the registry during
// SDK initialization.
val typesFlow: Flow<Set<DeviceType>> = device.types()

// Get a snapshot of all types.
val types: Set<DeviceType> = typesFlow.first()

// Get the DimmableLightDevice instance from the set of types.
val dimmableLightDevice = types.filterIsInstance<DimmableLightDevice>().firstOrNull()

// Get all traits in the type + traits registered
val allTraits: Set<Trait> = dimmableLightDevice!!.traits()

অন্য ধরনের ট্রেইট কলিশন হতে পারে যখন কোনও ডিভাইসে একই নামের দুটি ট্রেইট থাকে। যেমন, onOff স্ট্যান্ডার্ড OnOff ট্রেইটের কোনও ইনস্ট্যান্সকে রেফার করতে পারে অথবা এটি কোনও ম্যানুফ্যাকচারার-ডিফাইন করা OnOff ট্রেইটের ইনস্ট্যান্সকে রেফার করতে পারে। কোন বৈশিষ্ট্যটি ব্যবহার করা হবে তা নিয়ে কোনও অস্পষ্টতা দূর করতে, ডিভাইসের মাধ্যমে রেফারেন্স করা Trait ইনস্ট্যান্সের আগে একটি কোয়ালিফাইং নেমস্পেস থাকতে হবে। স্ট্যান্ডার্ড বৈশিষ্ট্যের জন্য, অর্থাৎ, যেগুলি Matter স্ট্যান্ডার্ড ক্লাস্টারের অনুরূপ, standardTraits ব্যবহার করুন। Google বৈশিষ্ট্যের জন্য, googleTraits ব্যবহার করুন:

// Accessing standard traits on the type.
val onOffTrait: OnOff? = dimmableLightDevice.standardTraits.onOff
val levelControlTrait: LevelControl? = dimmableLightDevice.standardTraits.levelControl

প্রস্তুতকারক-নির্দিষ্ট বৈশিষ্ট্য অ্যাক্সেস করতে, সরাসরি এটি উল্লেখ করুন:

// Accessing a custom trait on the type.
val customTrait = dimmableLightDevice.trait(MyCustomTrait)

নির্দিষ্ট বৈশিষ্ট্য সহ ডিভাইসের তালিকা পান

Kotlin-এ filter ফাংশন ব্যবহার করে API কল আরও রিফাইন করা যেতে পারে। যেমন, বাড়িতে থাকা এমন সব ডিভাইসের তালিকা পেতে যেগুলির চালু/বন্ধ করার বৈশিষ্ট্য আছে:

// Get all devices that support OnOff
val onOffDevices: Flow<List<HomeDevice>> =
  home.devices().map { devices -> devices.filter { it.has(OnOff) } }

Home API-তে উপলভ্য বৈশিষ্ট্যের সম্পূর্ণ তালিকা পেতে Trait ইন্টারফেস দেখুন।

একই ধরনের ডিভাইসের তালিকা পান

বাড়ির সব আলো দেখায় এমন ডিভাইসের তালিকা পেতে:

// Get a list of devices with similar device types (lights)
val lightDevices =
  home.devices().map { devices ->
    devices.filter {
      it.has(DimmableLightDevice) ||
        it.has(OnOffLightDevice) ||
        it.has(ColorTemperatureLightDevice) ||
        it.has(ExtendedColorLightDevice)
    }
  }

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

Home API-তে উপলভ্য ডিভাইসের ধরনের সম্পূর্ণ তালিকা দেখতে DeviceType ইন্টারফেস দেখুন।

কোনও ডিভাইসের জন্য ভেন্ডর আইডি বা প্রোডাক্ট আইডি পান

BasicInformation বৈশিষ্ট্যে ভেন্ডর আইডি, প্রোডাক্ট আইডি, প্রোডাক্টের নাম ও ডিভাইসের ক্রমিক সংখ্যার মতো তথ্য অন্তর্ভুক্ত থাকে:

// Get device basic information. All general information traits are on the RootNodeDevice type.
val basicInformation = device.type(RootNodeDevice).first().standardTraits.basicInformation!!
println("vendorName ${basicInformation.vendorName}")
println("vendorId ${basicInformation.vendorId}")
println("productId ${basicInformation.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 API-তে ডিভাইস ও বৈশিষ্ট্যের সাথে মেটাডেটা যুক্ত থাকে, যা কোনও অ্যাপে ব্যবহারকারীর অভিজ্ঞতা ম্যানেজ করতে সাহায্য করতে পারে।

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

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

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

প্রথমে, type() ব্যবহার করে ডিভাইসের ধরন(গুলি) পান, তারপর প্রাথমিক ধরন(গুলি) নির্ধারণ করুন:

val types = device.types().first()
val primaryTypes = types.filter { it.metadata.isPrimaryType }

কোনও বৈশিষ্ট্য অনলাইন কিনা তা চেক করুন

কোনও বৈশিষ্ট্যের কানেক্টিভিটি চেক করতে connectivityState() পদ্ধতি ব্যবহার করুন:

val onOffConnectivity = onOffTrait?.metadata?.sourceConnectivity?.connectivityState

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

কোনও ডিভাইসের কানেক্টিভিটি চেক করা

ডিভাইসের কানেক্টিভিটি আসলে ডিভাইসের ধরন লেভেলে চেক করা হয় কারণ কিছু ডিভাইস একাধিক ডিভাইসের ধরন সাপোর্ট করে। যে স্ট্যাটাস দেখানো হয় তা হল সেই ডিভাইসের সব বৈশিষ্ট্যের জন্য কানেক্টিভিটি স্ট্যাটাসের কম্বিনেশন।

val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState

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

ডিভাইসের IP অ্যাড্রেস পান

ডিভাইসের IP অ্যাড্রেস খুঁজে পেতে, GeneralDiagnostics ট্রেটের networkInterfaces অ্যাট্রিবিউট ব্যবহার করুন। অ্যাড্রেসগুলি বাইট অ্যারে হিসেবে ফেরত পাঠানো হয়, যেগুলি আপনি স্ট্যান্ডার্ড IPv4 বা IPv6 স্ট্রিংয়ে ফর্ম্যাট করতে পারেন:

val ipAddresses =
  trait.networkInterfaces?.flatMap { networkInterface ->
    (networkInterface.ipv4Addresses + networkInterface.ipv6Addresses).mapNotNull { bytes ->
      try {
        java.net.InetAddress.getByAddress(bytes).hostAddress
      } catch (e: java.net.UnknownHostException) {
        null
      }
    }
  } ?: emptyList()

কোনও ট্রেইটের নেটওয়ার্ক রাউটিং চেক করুন

Home API-তে কোনও ট্রেইটের লোকালিটিও উপলভ্য। dataSourceLocality থেকে বোঝা যায় যে ট্রেইটটি রিমোটলি (ক্লাউডের মাধ্যমে), লোকালি (লোকাল হাবের মাধ্যমে) নাকি পিয়ার-টু-পিয়ার (সরাসরি ডিভাইস থেকে ডিভাইসে, কোনও হাব নেই) রাউট করা হয়েছে।

অজানা লোকালিটি ভ্যালু UNSPECIFIED হতে পারে, যেমন, কোনও অ্যাপ বুট করার সময় এবং ডিভাইস কানেক্টিভিটির জন্য এখনও কোনও হাব বা সার্ভারে পৌঁছায়নি। এইসব ডিভাইস অ্যাক্সেস করা যাচ্ছে না এবং কমান্ড বা ইভেন্ট থেকে ইন্টার‍্যাকশনের অনুরোধ ব্যর্থ হবে। এই ধরনের ডিভাইস কীভাবে ম্যানেজ করা হবে তা ক্লায়েন্টকে নির্ধারণ করতে হবে।

val onOffLocality = onOffTrait?.metadata?.sourceConnectivity?.dataSourceLocality

কোনও ডিভাইসের জন্য নেটওয়ার্ক রাউটিং চেক করা

কানেক্টিভিটির মতো, ডিভাইসের ধরন অনুযায়ী লোকালিটি চেক করা হয়। যে স্ট্যাটাস ফেরত পাঠানো হয় তা হল সেই ডিভাইসের সব বৈশিষ্ট্যের জন্য লোকালিটির কম্বিনেশন।

val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality

PARTIALLY_ONLINE কানেক্টিভিটির মতো একই পরিস্থিতিতে MIXED-এর স্ট্যাটাস দেখা যেতে পারে: কিছু বৈশিষ্ট্য ক্লাউড-ভিত্তিক হলেও অন্যগুলি লোকাল।

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

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

mixerDevice.setName("Grendel")

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

কোনও ডিভাইসের জন্য গ্রুপ মেম্বারশিপ চেক করা

একটি ফিজিক্যাল ডিভাইস এক বা একাধিক ডিভাইস গ্রুপের অন্তর্গত হতে পারে। কোনও ডিভাইস কোন গ্রুপের অন্তর্গত তা দেখতে, ডিভাইসে GroupMembership বৈশিষ্ট্য চেক করুন:

val groupIds = device.trait(GroupMembershipTrait)?.groupObjectIds.orEmpty()
for (groupId in groupIds) {
  println("HomeAPI", "Device belongs to group: $groupId")
}

বিপরীতভাবে, আপনি DeviceGroup-এ devices() ফ্লো কল করে DeviceGroup-এর অন্তর্গত সব মেম্বার ডিভাইস দেখতে পারবেন:

group.devices(enableMultipartDevices = true).collect { members ->
  println("HomeAPI", "Group contains ${members.size} devices")
}

DeviceGroup-এর মাধ্যমে কাজ করে এমন ডিভাইসের ধরন পরীক্ষা করতে এবং গ্রুপে একটি এন্টিটি হিসেবে কমান্ড পাঠাতে, ডিভাইস গ্রুপ নিয়ন্ত্রণ করুন বিকল্প দেখুন।