Mengakses perangkat dan metadata perangkat

Device API dapat diakses melalui Home API. 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 jenis perangkat Unit Plugin Aktif/Nonaktif dan karakteristik Aktif/Nonaktif Matter, 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.

Penanganan error

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

Saat menangani HomeException, periksa kolom code dan message untuk mengetahui masalahnya.

Setiap pengecualian yang tidak ditangani akan menyebabkan aplikasi Anda error.

Untuk mengetahui informasi selengkapnya, lihat Penanganan error.

Lihat Mengirim perintah ke perangkat untuk contoh.

Contoh panggilan

Mendapatkan daftar perangkat

Dengan struktur yang tersedia, panggilan devices() akan menampilkan Alur perangkat yang dapat diakses oleh Anda 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 untuk 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 karakteristik Home API, dengan karakteristik ini diidentifikasi sebagai OnOff, Anda dapat mengambil data karakteristik 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 fungsi alur Kotlin lebih lanjut.

Membatalkan validasi status dalam langganan sifat

Antarmuka TraitStateInvalidation memberikan kemampuan untuk membatalkan 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 karakteristik Matter dengan kualitas "C" atau karena implementasi perangkat yang tiba-tiba menyebabkan masalah.

API ini mengeluarkan pembacaan paksa status sifat saat ini dan menampilkan hasilnya melalui alur sifat 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 karakteristik, karena mendekomposisi perangkat menjadi bagian fungsional (seperti endpoint di Matter).

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

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

// 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 sifat lain dapat terjadi saat perangkat memiliki dua sifat dengan nama yang sama. Misalnya, onOff dapat merujuk ke instance karakteristik OnOff standar, atau dapat merujuk ke instance karakteristik OnOff yang ditentukan produsen. Untuk menghilangkan potensi ambiguitas terkait sifat yang dimaksud, instance Trait yang direferensikan melalui perangkat harus didahului oleh namespace yang memenuhi syarat. Untuk atribut standar, yaitu atribut 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, referensikan secara 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 menyaring panggilan API. Misalnya, untuk mendapatkan daftar perangkat di rumah yang semuanya memiliki karakteristik Aktif/Nonaktif:

// 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 sifat 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 mewakili jenis perangkat inti. Misalnya, tidak ada jenis perangkat "Lampu". Sebagai gantinya, ada empat jenis perangkat berbeda yang dapat mewakili lampu, seperti yang ditunjukkan dalam contoh sebelumnya. Dengan demikian, untuk mendapatkan tampilan komprehensif tentang jenis perangkat tingkat 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

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

Mengidentifikasi perangkat Cloud-to-cloud

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

  • ID vendor yang diterbitkan oleh Connectivity Standards Alliance (CSA): "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 serta 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 informasi selengkapnya, lihat dokumentasi Cloud-to-cloud SYNC.

Metadata perangkat dan fitur

Perangkat dan karakteristik 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 (rute lokal atau jarak jauh).

Mendapatkan jenis utama perangkat

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

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

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

Memeriksa apakah suatu karakteristik sedang online

Gunakan metode connectivityState() untuk memeriksa konektivitas sifat:

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

Beberapa karakteristik, biasanya karakteristik smart home Google, dapat ditampilkan secara offline jika perangkat tidak memiliki konektivitas internet. Hal ini karena sifat ini berbasis cloud dan tidak memiliki pemilihan rute lokal.

Memeriksa konektivitas untuk 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. Atribut standar Matter mungkin masih online karena pemilihan rute lokal, tetapi atribut berbasis cloud akan offline.

Memeriksa perutean jaringan suatu karakteristik

Lokalitas untuk suatu karakteristik juga tersedia di Home API. dataSourceLocality menunjukkan apakah sifat 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 mungkin terjadi, misalnya, saat aplikasi di-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 dapat 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, sedangkan karakteristik lainnya bersifat lokal.

Daftar API

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

API Deskripsi
devices() Mendapatkan semua perangkat di semua struktur di Akun Google. Menampilkan HomeObjectsFlow yang menyediakan opsi pengambilan dan pemfilteran lebih lanjut.

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

API Deskripsi
allCandidates() Menampilkan semua kandidat otomatisasi untuk perangkat dan turunannya.
candidates() Menampilkan semua kandidat otomatisasi untuk perangkat.
connectivityStateChanged Waktu terakhir kali status perangkat berubah.
events(event) Mendapatkan alur Peristiwa tertentu.
events(trait) Mendapatkan alur semua Peristiwa menurut Atribut ini.
events(traits) Mendapatkan alur semua Peristiwa menurut Atribut ini.
getSourceConnectivity(trait) Mendapatkan metadata untuk sifat tertentu. Menampilkan SourceConnectivity.
has(trait) Periksa apakah karakteristik yang diminta saat ini didukung oleh perangkat.
has(type) Jika perangkat mendukung jenis yang disediakan.
id ID sistem unik perangkat.
isInRoom Jika perangkat berada di ruangan.
isInStructure Jika perangkat berada dalam struktur.
isMatterDevice Jika perangkat didukung oleh Matter.
name Nama perangkat yang diberikan pengguna.
room() Ruang tempat perangkat ditetapkan. Menampilkan Room.
roomId ID kamar tempat perangkat ditetapkan. Menampilkan Id.
sourceConnectivity Konektivitas sumber perangkat, yang mewakili status konektivitas gabungan dan lokalitas jaringan dari karakteristik perangkat.
structure() Struktur tempat perangkat ditetapkan. Menampilkan Structure.
structureId ID struktur tempat perangkat ditetapkan. Menampilkan Id.
type(type) Dapatkan definisi jenis dengan mengisi karakteristik (jika tersedia) untuk akses langsung. Selalu menampilkan snapshot terbaru dari karakteristik.
types() Dapatkan daftar semua jenis yang tersedia di perangkat.