Mengakses perangkat dan metadata perangkat untuk Android

API Perangkat dapat diakses melalui Home API untuk Android. Impor paket ini ke aplikasi Anda:

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

Untuk menggunakan jenis atau karakteristik perangkat tertentu dengan Device API, jenis atau karakteristik tersebut harus diimpor satu per satu.

Misalnya, untuk menggunakan trait Aktif/Nonaktif Matter dan jenis perangkat Unit Plug-in Aktif/Nonaktif, impor paket berikut ke dalam aplikasi Anda:

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

Untuk mengetahui informasi selengkapnya, lihat Model data di Android.

Penanganan error

Setiap metode di Home API dapat memunculkan HomeException, jadi sebaiknya gunakan blok try-catch untuk menangkap HomeException pada semua panggilan.

Saat menangani HomeException, periksa kolom code dan message untuk mengetahui apa yang salah.

Setiap pengecualian yang tidak ditangani akan menyebabkan aplikasi Anda error.

Untuk mengetahui informasi selengkapnya, lihat Penanganan error.

Lihat Mengirim perintah ke perangkat untuk contohnya.

Contoh panggilan

Mendapatkan daftar perangkat

Dengan tersedianya struktur, panggilan devices() akan menampilkan Flow perangkat yang dapat Anda akses dari struktur tersebut:

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

Dari sana, status setiap perangkat dapat diakses, dan perintah yang didukung dapat dikirim ke perangkat.

Membaca status perangkat

Mari kita lihat contoh pemeriksaan atribut OnOff dari sifat Aktif/Nonaktif perangkat. Dengan menggunakan model data trait Home APIs, yang mengidentifikasi trait ini sebagai OnOff, Anda dapat mengambil data trait melalui class standardTraits jenis perangkat:

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

Lihat distinctUntilChanged untuk mempelajari lebih lanjut fungsi alur Kotlin.

Membatalkan status dalam langganan trait

Antarmuka TraitStateInvalidation memberikan kemampuan untuk membatalkan validasi status yang diambil melalui langganan ke perangkat target jika status tidak dilaporkan dengan benar. Contoh saat status mungkin tidak dilaporkan dengan benar mencakup penggunaan atribut dalam ciri Matter dengan kualitas "C" atau karena penerapan perangkat yang menyebabkan masalah secara tidak terduga.

API ini mengeluarkan pembacaan paksa status karakteristik saat ini dan menampilkan hasilnya melalui alur karakteristik yang ada.

Dapatkan sifat, lalu jalankan forceRead pada sifat:

val generalDiagnosticsTrait = device.trait(GeneralDiagnostics).first()
generalDiagnosticsTrait.forceRead()

Mendapatkan daftar fitur jenis perangkat

Jenis perangkat harus digunakan sebagai titik entri untuk membaca trait, karena jenis perangkat menguraikan perangkat menjadi bagian-bagian fungsionalnya (seperti endpoint di Matter).

ID ini juga memperhitungkan konflik karakteristik jika perangkat memiliki dua jenis perangkat, yang keduanya mungkin memiliki karakteristik yang sama. Misalnya, jika perangkat adalah Speaker dan Lampu yang Dapat Diredupkan, perangkat tersebut akan memiliki dua sifat On/Off dan dua sifat Kontrol Level.

Untuk mendapatkan daftar karakteristik yang tersedia untuk jenis perangkat Lampu yang Dapat Diredupkan:

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

Jenis tabrakan karakteristik lainnya dapat terjadi saat perangkat memiliki dua karakteristik dengan nama yang sama. Misalnya, onOff dapat merujuk ke instance sifat OnOff standar, atau dapat merujuk ke instance sifat OnOff yang ditentukan produsen. Untuk menghilangkan potensi ambiguitas terkait sifat yang dimaksud, instance Trait yang dirujuk melalui perangkat harus didahului dengan namespace yang memenuhi syarat. Untuk sifat standar, yaitu yang analog dengan cluster standar Matter, gunakan standardTraits. Untuk karakteristik Google, gunakan googleTraits:

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

Untuk mengakses karakteristik khusus produsen, rujuk langsung:

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

Mendapatkan daftar perangkat dengan karakteristik tertentu

Fungsi filter di Kotlin dapat digunakan untuk lebih menyempurnakan panggilan API. Misalnya, untuk mendapatkan daftar perangkat di rumah yang semuanya memiliki trait On/Off:

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

Lihat antarmuka Trait untuk mengetahui daftar lengkap karakteristik yang tersedia di Home API.

Mendapatkan daftar perangkat dengan jenis perangkat yang serupa

Untuk mendapatkan daftar perangkat yang mewakili semua lampu di rumah:

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

Ada beberapa jenis perangkat di Home API yang dapat merepresentasikan jenis perangkat inti. Misalnya, tidak ada jenis perangkat "Lampu". Sebagai gantinya, ada empat jenis perangkat berbeda yang dapat merepresentasikan lampu, seperti yang ditunjukkan dalam contoh sebelumnya. Oleh karena itu, untuk mendapatkan tampilan komprehensif jenis perangkat tingkat yang lebih tinggi di rumah, beberapa jenis perangkat harus disertakan dalam alur yang difilter.

Lihat antarmuka DeviceType untuk mengetahui daftar lengkap jenis perangkat yang tersedia di Home API.

Mendapatkan ID Vendor atau ID Produk untuk perangkat

Trait BasicInformation mencakup informasi seperti ID Vendor, ID Produk, Nama Produk, dan Nomor Seri untuk perangkat:

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

Identifikasi perangkat cloud-ke-cloud untuk produsen perangkat

Jika Anda adalah pembuat perangkat dan membuat perangkat Cloud-to-cloud, untuk mengidentifikasi perangkat Cloud-to-cloud melalui trait BasicInformation, Anda dapat menyertakan kolom string ini dalam respons SYNC:

• Connectivity Standards Alliance (CSA) mengeluarkan ID vendor: "matterOriginalVendorId": "0xfff1",

• ID Produk yang mengidentifikasi produk vendor secara unik: "matterOriginalProductId": "0x1234",

• ID unik untuk perangkat, yang dibuat dengan cara khusus produsen: "matterUniqueId": "matter-device-id",

Saat memasukkan kolom string ini, gunakan Matter ID Vendor dan Produk jika Anda memilikinya. Jika Anda bukan anggota CSA dan belum diberi ID ini, Anda dapat mengosongkan kolom matterOriginalVendorId dan matterOriginalProductId, lalu memberikan matterUniqueId sebagai ID.

Contoh respons SYNC menunjukkan penggunaan kolom ini:

{
  "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",
          }
        ]
      }
    ]
  }
}

Untuk mengetahui informasi selengkapnya, lihat dokumentasi Cloud-to-cloud SYNC.

Metadata perangkat dan karakteristik

Perangkat dan fitur di Home API memiliki metadata yang terkait dengannya, yang dapat membantu mengelola pengalaman pengguna di aplikasi.

Setiap karakteristik di Home API berisi properti sourceConnectivity, yang memiliki informasi tentang status online dan lokalitas karakteristik (perutean lokal atau jarak jauh).

Mendapatkan jenis utama perangkat

Beberapa perangkat dapat menampilkan beberapa jenis perangkat melalui Home API. Untuk memastikan pengguna melihat opsi yang sesuai di aplikasi (seperti kontrol perangkat dan otomatisasi yang disarankan) untuk perangkat mereka, sebaiknya periksa jenis perangkat utama untuk suatu perangkat.

Pertama, dapatkan jenis perangkat menggunakan type(), lalu tentukan jenis utama:

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

Memeriksa apakah suatu sifat tersedia secara online

Gunakan metode connectivityState() untuk memeriksa konektivitas trait:

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

Beberapa karakteristik, biasanya karakteristik Google smart home, mungkin ditampilkan offline jika perangkat tidak memiliki konektivitas internet. Hal ini karena trait ini berbasis cloud dan tidak memiliki perutean lokal.

Memeriksa konektivitas perangkat

Konektivitas untuk perangkat sebenarnya diperiksa di tingkat jenis perangkat karena beberapa perangkat mendukung beberapa jenis perangkat. Status yang ditampilkan adalah kombinasi status konektivitas untuk semua fitur di perangkat tersebut.

val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState

Status PARTIALLY_ONLINE dapat diamati dalam kasus jenis perangkat campuran saat tidak ada konektivitas internet. Ciri standar Matter mungkin masih online karena perutean lokal, tetapi ciri berbasis cloud akan offline.

Memeriksa perutean jaringan trait

Lokalitas untuk sifat juga tersedia di Home API. dataSourceLocality menunjukkan apakah trait dirutekan dari jarak jauh (melalui cloud), secara lokal (melalui hub lokal), atau peer-to-peer (langsung dari perangkat ke perangkat, tanpa hub).

Nilai lokalitas yang tidak diketahui UNSPECIFIED dapat terjadi, misalnya, saat aplikasi sedang melakukan booting dan belum mencapai hub atau server untuk konektivitas perangkat. Perangkat ini tidak dapat dijangkau dan akan gagal dalam permintaan interaksi dari perintah atau peristiwa. Klien yang menentukan cara menangani perangkat tersebut.

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

Memeriksa perutean jaringan untuk perangkat

Seperti konektivitas, lokalitas diperiksa di tingkat jenis perangkat. Status yang ditampilkan adalah kombinasi lokalitas untuk semua fitur di perangkat tersebut.

val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality

Status MIXED dapat diamati dalam skenario yang serupa dengan konektivitas PARTIALLY_ONLINE: beberapa karakteristik berbasis cloud, sementara yang lain bersifat lokal.

Mengubah nama perangkat

Panggil metode setName() untuk mengubah nama perangkat:

mixerDevice.setName("Grendel")

Nama akan dipangkas jika melebihi batas 60 poin kode Unicode (karakter) dan tidak ada error yang akan ditampilkan. Developer bertanggung jawab untuk menangani nama panjang dan, misalnya, dapat memutuskan apakah mereka ingin memberi tahu pengguna bahwa nama akan dipangkas.

Daftar API

Setelah instance Home dibuat, API Perangkat berikut dapat diakses melalui instance tersebut:

Setelah Anda memiliki HomeDevice, API berikut dapat diakses melalui HomeDevice: