Device API 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 karakteristik On/Off Matter dan jenis perangkat Unit Plug-in On/Off, 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 menampilkan
HomeException, jadi sebaiknya gunakan blok try-catch untuk
menangkap HomeException di semua panggilan.
Saat menangani HomeException, periksa kolom
error.code dan
error.message untuk mengetahui penyebab masalahnya. Mungkin juga ada sub-kode error, jadi panggil metode
getSubErrorCodes() dan periksa hasilnya.
Setiap pengecualian yang tidak ditangani akan menyebabkan aplikasi Anda error.
Untuk mengetahui informasi selengkapnya, lihat Penanganan error.
Lihat Mengirim perintah ke perangkat untuk mengetahui contohnya.
Contoh panggilan
Mendapatkan daftar perangkat
Setelah Anda memiliki referensi ke instance Structure, 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, Anda dapat mengakses status untuk setiap perangkat dan mengirim perintah ke perangkat.
Dengan rilis 1.8 API Home, Anda memiliki opsi untuk membuat API merepresentasikan
setiap perangkat multibagian sebagai satu perangkat dengan menetapkan parameter enableMultipartDevices
metode devices() ke true. Lihat
Perangkat multibagian di Android untuk mengetahui informasi
selengkapnya.
Membaca status perangkat
Lihat contoh pemeriksaan atribut OnOff dari karakteristik
On/Off perangkat. Dengan menggunakan model data karakteristik Home API, yang mengidentifikasi karakteristik ini 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 lebih lanjut fungsi flow Kotlin.
Membatalkan status dalam langganan karakteristik
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 secara tidak terduga menyebabkan masalah.
API ini mengeluarkan pembacaan paksa status karakteristik saat ini dan menampilkan hasilnya melalui alur karakteristik yang ada.
Dapatkan karakteristik, lalu jalankan forceRead pada karakteristik:
val onOffTrait = device.?type(DimmableLightDevice)?.map{it.trait(OnOff)}.first()
onOffTrait.forceRead()
Mendapatkan daftar karakteristik jenis perangkat
Jenis perangkat harus digunakan sebagai titik entri untuk membaca karakteristik, karena jenis perangkat menguraikan perangkat menjadi bagian-bagian fungsionalnya (seperti endpoint di Matter).
Fitur ini juga memperhitungkan tabrakan karakteristik jika perangkat memiliki dua jenis perangkat, yang keduanya mungkin memiliki karakteristik yang sama. Misalnya, jika perangkat merupakan Speaker dan Lampu yang Dapat Diredupkan, perangkat tersebut akan memiliki dua karakteristik On/Off dan dua karakteristik Level Control.
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 ciri lainnya dapat terjadi jika perangkat memiliki dua ciri 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 karakteristik yang
dimaksud, instance Trait yang direferensikan melalui perangkat harus didahului dengan
namespace yang memenuhi syarat. Untuk karakteristik 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, 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 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 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. Oleh karena itu, untuk mendapatkan tampilan komprehensif dari 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
Karakteristik 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-to-cloud untuk produsen perangkat
Jika Anda adalah pembuat perangkat dan membuat perangkat Cloud-to-cloud,
untuk mengidentifikasi perangkat
Cloud-to-cloud Anda melalui
sifat BasicInformation, Anda dapat menyertakan kolom string ini dalam
respons SYNC:
ID vendor yang dikeluarkan Connectivity Standards Alliance (Alliance):
"matterOriginalVendorId": "0xfff1",Kode Produk yang secara unik mengidentifikasi produk vendor:
"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
Alliance dan belum diberi ID ini, Anda dapat
mengosongkan kolom matterOriginalVendorId dan matterOriginalProductId
serta memberikan matterUniqueId sebagai ID.
Contoh respons SYNC menunjukkan penggunaan kolom berikut:
{
"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 karakteristik di Home API memiliki metadata yang terkait, 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 mungkin 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 perangkat.
Pertama, dapatkan jenis perangkat menggunakan
type(),
lalu tentukan jenis utamanya:
val types = device.types().first() val primaryTypes = types.filter { it.metadata.isPrimaryType }
Memeriksa apakah ciri sedang online
Gunakan metode connectivityState() untuk memeriksa konektivitas karakteristik:
val onOffConnectivity = onOffTrait?.metadata?.sourceConnectivity?.connectivityState
Beberapa karakteristik, biasanya karakteristik smart home Google, mungkin ditampilkan offline jika perangkat tidak memiliki konektivitas internet. Hal ini karena karakteristik ini berbasis cloud dan tidak memiliki perutean 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 karakteristik di perangkat tersebut.
val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState
Status PARTIALLY_ONLINE dapat diamati dalam kasus
jenis perangkat campuran saat tidak ada konektivitas internet.
Karakteristik standar Matter mungkin masih online karena perutean lokal, tetapi karakteristik berbasis cloud akan offline.
Mendapatkan alamat IP perangkat
Untuk menemukan alamat IP perangkat, gunakan atribut networkInterfaces dari karakteristik GeneralDiagnostics. Alamat ditampilkan sebagai array byte, yang dapat Anda format menjadi string IPv4 atau IPv6 standar:
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()
Memeriksa pemilihan rute jaringan suatu karakteristik
Lokalitas untuk karakteristik juga tersedia di Home API. dataSourceLocality menunjukkan apakah karakteristik 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 menggagalkan permintaan interaksi dari perintah atau peristiwa. Klien dapat menentukan cara menangani perangkat tersebut.
val onOffLocality = onOffTrait?.metadata?.sourceConnectivity?.dataSourceLocality
Memeriksa pemilihan rute jaringan untuk perangkat
Seperti konektivitas, lokalitas diperiksa di tingkat jenis perangkat. Status yang ditampilkan adalah kombinasi lokalitas untuk semua karakteristik 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 dipotong jika melebihi batas 60 poin kode Unicode (karakter) dan tidak akan ada error yang ditampilkan. Developer bertanggung jawab untuk menangani nama yang panjang dan, misalnya, dapat memutuskan apakah mereka ingin memberi tahu pengguna bahwa nama akan dipotong.
Memeriksa keanggotaan grup untuk perangkat
Perangkat fisik dapat menjadi bagian dari satu atau beberapa grup perangkat. Untuk melihat grup
tempat perangkat berada, periksa
karakteristik
GroupMembership pada perangkat:
val groupIds = device.trait(GroupMembershipTrait)?.groupObjectIds.orEmpty()
for (groupId in groupIds) {
println("HomeAPI", "Device belongs to group: $groupId")
}
Sebaliknya, Anda dapat mengamati semua perangkat anggota yang termasuk dalam
DeviceGroup dengan memanggil
alur devices() di DeviceGroup:
group.devices(enableMultipartDevices = true).collect { members ->
println("HomeAPI", "Group contains ${members.size} devices")
}
Untuk memeriksa jenis perangkat yang didukung oleh DeviceGroup dan mengirim perintah ke
grup sebagai satu entity, lihat
Mengontrol grup perangkat.