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. |