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

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

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

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

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

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

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

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

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

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

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

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

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

নমুনা কল

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

কাঠামো উপলব্ধ থাকলে, একটি devices() কল সেই কাঠামো থেকে আপনার কাছে অ্যাক্সেসযোগ্য ডিভাইসের একটি প্রবাহ ফেরত দেয়:

// 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()

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

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

ডিভাইসের On/Off বৈশিষ্ট্য থেকে OnOff বৈশিষ্ট্যটি পরীক্ষা করার একটি উদাহরণ দেখি। Home APIs বৈশিষ্ট্য ডেটা মডেল ব্যবহার করে, যেখানে এই বৈশিষ্ট্যটি 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()!!

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

একটি বৈশিষ্ট্য সাবস্ক্রিপশনের অবস্থা অবৈধ করুন

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

এই API বর্তমান বৈশিষ্ট্যের অবস্থার একটি জোরপূর্বক পঠন জারি করে এবং বিদ্যমান বৈশিষ্ট্য প্রবাহের মাধ্যমে ফলাফল প্রদান করে।

বৈশিষ্ট্যটি পান, তারপর একটি forceRead প্রয়োগ করুন বৈশিষ্ট্যটির উপর পড়ুন:

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

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

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

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

Dimmable Light ডিভাইসের ধরণের জন্য উপলব্ধ বৈশিষ্ট্যগুলির তালিকা পেতে:

// 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) } }

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

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

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

• কানেক্টিভিটি স্ট্যান্ডার্ডস অ্যালায়েন্স (CSA) বিক্রেতা আইডি জারি করেছে: "matterOriginalVendorId": "0xfff1",

• একটি পণ্য শনাক্তকারী যা একজন বিক্রেতার পণ্যকে অনন্যভাবে শনাক্ত করে: "matterOriginalProductId": "0x1234",

• ডিভাইসের জন্য একটি অনন্য শনাক্তকারী, যা প্রস্তুতকারক-নির্দিষ্ট পদ্ধতিতে তৈরি করা হয়: "matterUniqueId": "matter-device-id",

এই স্ট্রিং ফিল্ডগুলিতে প্রবেশ করার সময়, আপনার Matter ভেন্ডর এবং প্রোডাক্ট আইডি থাকলে তা ব্যবহার করুন। আপনি যদি CSA সদস্য না হন এবং এই আইডিগুলি আপনাকে বরাদ্দ না করা হয়, তাহলে আপনি 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 বৈশিষ্ট্য থাকে, যার মধ্যে একটি বৈশিষ্ট্যের অনলাইন অবস্থা এবং স্থানীয়তা (স্থানীয় বা দূরবর্তী রাউটিং) সম্পর্কে তথ্য থাকে।

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

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

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

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

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

একটি বৈশিষ্ট্যের সংযোগ পরীক্ষা করতে connectivityState() পদ্ধতি ব্যবহার করুন:

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

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

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

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

val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState

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

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

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

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

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

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

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

val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality

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

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

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

mixerDevice.setName("Grendel")

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

API তালিকা

একবার Home একটি ইনস্ট্যান্স তৈরি হয়ে গেলে, নিম্নলিখিত ডিভাইস API গুলি এর মাধ্যমে অ্যাক্সেসযোগ্য হয়:

একবার আপনার একটি HomeDevice হয়ে গেলে, নিম্নলিখিত API গুলি এর মাধ্যমে অ্যাক্সেসযোগ্য হবে: