Device API dapat diakses melalui Home API untuk Android. Impor paket ini ke dalam aplikasi Anda:
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.Id
Untuk menggunakan jenis atau fitur perangkat tertentu dengan Device API, jenis atau fitur tersebut harus diimpor satu per satu.
Misalnya, untuk menggunakan fitur Matter On/Off dan jenis perangkat On/Off Plug-in Unit, 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
Metode apa pun di Home API dapat menampilkan
HomeException, jadi sebaiknya gunakan blok try-catch untuk
menangkap HomeException pada semua panggilan.
Saat menangani HomeException, periksa kolom
error.code dan
error.message untuk mengetahui penyebab masalah. Mungkin ada juga kode sub-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.
Panggilan sampel
Mendapatkan daftar perangkat
Setelah 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 Home API versi 1.8, Anda memiliki opsi untuk membuat API menampilkan setiap perangkat multipart sebagai satu perangkat dengan menetapkan parameter enableMultipartDevices metode devices() ke true. Lihat
Perangkat multipart di Android untuk mengetahui informasi selengkapnya.
Membaca status perangkat
Lihat contoh pemeriksaan atribut OnOff dari fitur On/Off perangkat. Dengan model data fitur Home API, tempat fitur ini diidentifikasi sebagai OnOff, Anda dapat mengambil data fitur 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 aliran Kotlin lebih lanjut.
Membatalkan status dalam langganan fitur
Antarmuka TraitStateInvalidationmemberikan kemampuan untuk membatalkan status yang diambil melalui langganan
ke perangkat target jika status tidak dilaporkan dengan benar.
Contohnya, status mungkin tidak dilaporkan dengan benar jika menyertakan
menggunakan atribut dalam fitur Matter dengan kualitas "C"
atau karena implementasi perangkat yang menyebabkan masalah secara tidak terduga.
API ini mengeluarkan pembacaan paksa status fitur saat ini dan menampilkan hasilnya melalui aliran fitur yang ada.
Dapatkan fitur, lalu jalankan forceRead pada fitur:
val onOffTrait = device.?type(DimmableLightDevice)?.map{it.trait(OnOff)}.first()
onOffTrait.forceRead()
Mendapatkan daftar fitur jenis perangkat
Jenis perangkat harus digunakan sebagai titik entri untuk membaca fitur, karena jenis perangkat menguraikan perangkat menjadi bagian-bagian fungsionalnya (seperti endpoint di Matter).
Jenis perangkat juga memperhitungkan konflik fitur jika perangkat memiliki dua jenis perangkat, yang keduanya mungkin memiliki fitur yang sama. Misalnya, jika perangkat adalah Speaker dan Lampu yang Dapat Diredupkan, perangkat tersebut akan memiliki dua fitur On/Off dan dua fitur Kontrol Level.
Untuk mendapatkan daftar fitur 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 konflik fitur lainnya dapat terjadi jika perangkat memiliki dua fitur dengan nama yang sama. Misalnya, onOff dapat merujuk ke instance fitur OnOff standar, atau dapat merujuk ke instance fitur OnOff yang ditentukan produsen. Untuk menghilangkan potensi ambiguitas terkait fitur mana yang dimaksud, instance Trait yang direferensikan melalui perangkat harus diawali dengan namespace yang memenuhi syarat. Untuk fitur standar, yaitu fitur yang analog dengan
Matter cluster standar, gunakan standardTraits. Untuk fitur Google, gunakan googleTraits:
// Accessing standard traits on the type. val onOffTrait: OnOff? = dimmableLightDevice.standardTraits.onOff val levelControlTrait: LevelControl? = dimmableLightDevice.standardTraits.levelControl
Untuk mengakses fitur khusus produsen, referensikan secara langsung:
// Accessing a custom trait on the type. val customTrait = dimmableLightDevice.trait(MyCustomTrait)
Mendapatkan daftar perangkat dengan fitur tertentu
Fungsi
filter
di Kotlin dapat digunakan untuk lebih menyempurnakan panggilan API. Misalnya, untuk mendapatkan daftar perangkat di rumah yang semuanya memiliki fitur 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
fitur yang tersedia di Home API.
Mendapatkan daftar perangkat dengan jenis perangkat 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 jenis perangkat tingkat yang lebih tinggi di rumah, beberapa jenis perangkat harus disertakan dalam aliran yang difilter.
Lihat antarmuka DeviceType
untuk mengetahui daftar lengkap jenis perangkat yang tersedia di Home API.
Mendapatkan ID Vendor atau ID Produk untuk perangkat
Fitur 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 produsen perangkat dan membuat Cloud-to-cloud perangkat,
untuk mengidentifikasi
Cloud-to-cloud perangkat Anda melalui
BasicInformation fitur, Anda dapat menyertakan kolom string ini dalam
respons SYNC mereka:
ID vendor yang dikeluarkan Connectivity Standards Alliance (Alliance)
"matterOriginalVendorId": "0xfff1",ID 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, 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
Cloud-to-cloud SYNC dokumentasi.
Metadata perangkat dan fitur
Perangkat dan fitur di Home API memiliki metadata yang terkait dengannya, yang dapat membantu mengelola pengalaman pengguna di aplikasi.
Setiap fitur di Home API berisi properti
sourceConnectivity, yang memiliki informasi tentang status online dan lokalitas fitur
(routing lokal atau jarak jauh).
Mendapatkan jenis utama perangkat
Beberapa perangkat dapat 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 primaryTypes = types.filter { it.metadata.isPrimaryType }
Memeriksa apakah fitur sedang online
Gunakan metode connectivityState() untuk memeriksa konektivitas fitur:
val onOffConnectivity = onOffTrait?.metadata?.sourceConnectivity?.connectivityState
Beberapa fitur, biasanya fitur Google smart home mungkin menampilkan status offline jika perangkat tidak memiliki konektivitas internet. Hal ini karena fitur ini berbasis cloud dan tidak memiliki routing 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 jika tidak ada konektivitas internet.
Matter Fitur standar mungkin masih online karena routing lokal, tetapi fitur berbasis cloud akan offline.
Mendapatkan alamat IP perangkat
Untuk menemukan alamat IP perangkat, gunakan atribut networkInterfaces dari
fitur
GeneralDiagnostics. Alamat ditampilkan sebagai array byte, yang dapat Anda format ke 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 routing jaringan fitur
Lokalitas untuk fitur juga tersedia di Home API. dataSourceLocality menunjukkan apakah fitur 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 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 harus menentukan cara menangani perangkat tersebut.
val onOffLocality = onOffTrait?.metadata?.sourceConnectivity?.dataSourceLocality
Memeriksa routing 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 fitur berbasis cloud, sedangkan 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 yang panjang dan, misalnya, dapat memutuskan apakah mereka ingin memberi tahu pengguna bahwa nama akan dipangkas.