Cihaz API'lerine Android için Home API'leri üzerinden erişilebilir. Bu paketleri uygulamanıza aktarın:
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.Id
Device API'lerle belirli cihaz türlerini veya özelliklerini kullanmak için bunların ayrı ayrı içe aktarılması gerekir.
Örneğin, Matter Açma/Kapatma özelliğini ve Açma/Kapatma Eklenti Birimi cihaz türünü kullanmak için aşağıdaki paketleri uygulamanıza aktarın:
import com.google.home.matter.standard.OnOff
import com.google.home.matter.standard.OnOffPluginUnitDevice
Daha fazla bilgi için Android'de veri modeli başlıklı makaleyi inceleyin.
Hata işleme
Home API'lerindeki tüm yöntemler
HomeException hatası verebilir. Bu nedenle, tüm çağrılarda HomeException hatasını yakalamak için try-catch bloğu kullanmanızı öneririz.
HomeException ile işlem yaparken neyin yanlış gittiğini öğrenmek için
error.code ve
error.message alanlarını kontrol edin. Alt hata kodları da olabilir. Bu nedenle
getSubErrorCodes() yöntemini çağırıp sonucu kontrol edin.
İşlenmeyen istisnalar uygulamanızın kilitlenmesine neden olur.
Daha fazla bilgi için Hata işleme bölümüne bakın.
Örnek için Cihaza komut gönderme başlıklı makaleyi inceleyin.
Örnek aramalar
Cihaz listesi alma
Structure örneğine referansınız olduğunda devices() çağrısı, bu yapıdan erişebileceğiniz cihazların Flow değerini döndürür:
// 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()
Buradan her cihazın durumuna erişebilir ve cihazlara komut gönderebilirsiniz.
Home API'lerinin 1.8 sürümünde, devices() yönteminin enableMultipartDevices parametresini true olarak ayarlayarak API'nin her çok parçalı cihazı tek bir cihaz olarak temsil etmesini sağlayabilirsiniz. Daha fazla bilgi için Android'de çok parçalı cihazlar başlıklı makaleyi inceleyin.
Cihaz durumunu okuma
Cihazın Açma/Kapatma özelliğinden OnOff özelliğini kontrol etme örneğine bakın. Bu özelliğin OnOff olarak tanımlandığı Home API'leri özellik veri modelini kullanarak cihaz türünün standardTraits sınıfı aracılığıyla özellik verilerini alabilirsiniz:
// 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()!!
distinctUntilChanged
sayfasını inceleyerek Kotlin akış işlevi hakkında daha fazla bilgi edinebilirsiniz.
Özellik aboneliğinde durumu geçersiz kılma
TraitStateInvalidation arayüzü,
hedef cihaz abonelikleri aracılığıyla alınan bir durumun doğru şekilde bildirilmediği durumlarda
bu durumu geçersiz kılma olanağı sağlar.
Durumun doğru şekilde bildirilmediği durumlara örnek olarak, Matter özelliklerinde "C" kalitesine sahip özelliklerin kullanılması veya beklenmedik bir şekilde soruna neden olan bir cihaz uygulaması verilebilir.
Bu API, mevcut özellik durumunun zorunlu olarak okunmasını sağlar ve sonucu mevcut özellik akışları üzerinden döndürür.
Özelliği alın, ardından özellik üzerinde bir forceRead çalıştırın:
val onOffTrait = device.?type(DimmableLightDevice)?.map{it.trait(OnOff)}.first()
onOffTrait.forceRead()
Cihaz türü özelliklerinin listesini alma
Cihaz türleri, cihazı işlevsel parçalarına (Matter içindeki uç noktalar gibi) ayırdığı için özellikleri okumak amacıyla giriş noktası olarak kullanılmalıdır.
Ayrıca, bir cihazda aynı özelliğe sahip iki cihaz türü varsa özellik çakışmalarını da hesaba katarlar. Örneğin, bir cihaz hem hoparlör hem de kısılabilir ışık ise iki Açma/Kapatma ve iki Seviye Kontrolü özelliğine sahip olur.
Kısılabilir Işık cihaz türü için kullanılabilen özelliklerin listesini almak istiyorsanız:
// 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()
Başka bir özellik çakışması türü, bir cihazın aynı ada sahip iki özelliği olduğunda ortaya çıkabilir. Örneğin, onOff, standart OnOff özelliğinin bir örneğini veya üretici tarafından tanımlanan OnOff özelliğinin bir örneğini ifade edebilir. Hangi özelliğin kastedildiğiyle ilgili olası belirsizlikleri ortadan kaldırmak için bir cihaz üzerinden referans verilen Trait örneğinin önüne uygun bir ad alanı eklenmelidir. Standart özellikler, yani Matter standart kümelerine benzer olanlar için standardTraits kullanın. Google özellikleri için googleTraits kullanın:
// Accessing standard traits on the type. val onOffTrait: OnOff? = dimmableLightDevice.standardTraits.onOff val levelControlTrait: LevelControl? = dimmableLightDevice.standardTraits.levelControl
Üreticiye özel bir özelliğe erişmek için doğrudan özelliğe referans verin:
// Accessing a custom trait on the type. val customTrait = dimmableLightDevice.trait(MyCustomTrait)
Belirli bir özelliğe sahip cihazların listesini alma
Kotlin'deki filter işlevi, API çağrılarını daha da hassaslaştırmak için kullanılabilir. Örneğin, evde Açma/Kapatma özelliğine sahip tüm cihazların listesini almak için:
// Get all devices that support OnOff val onOffDevices: Flow<List<HomeDevice>> = home.devices().map { devices -> devices.filter { it.has(OnOff) } }
Home API'lerinde kullanılabilen özelliklerin tam listesi için Trait arayüzüne bakın.
Benzer cihaz türlerine sahip cihazların listesini alma
Bir evdeki tüm ışıkları temsil eden cihazların listesini almak için:
// 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) } }
Home API'lerinde, temel cihaz türünü temsil edebilecek birden fazla cihaz türü vardır. Örneğin, "Işık" cihaz türü yoktur. Bunun yerine, önceki örnekte gösterildiği gibi bir ışığı temsil edebilecek dört farklı cihaz türü vardır. Bu nedenle, bir evdeki daha üst düzey cihaz türünün kapsamlı bir görünümünü elde etmek için filtrelenmiş akışlara birden fazla cihaz türü dahil edilmelidir.
Home API'lerinde kullanılabilen cihaz türlerinin tam listesi için DeviceType arayüzüne bakın.
Bir cihazın satıcı kimliğini veya ürün kimliğini alma
BasicInformation özelliği, bir cihazın Tedarikçi Kimliği, Ürün Kimliği, Ürün Adı ve Seri Numarası gibi bilgileri içerir:
// 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}")
Cihaz üreticileri için buluttan buluta cihaz tanımlama
Cihaz üreticisiyseniz ve Cloud-to-cloud cihazlar üretiyorsanız Cloud-to-cloud cihazlarınızı BasicInformation özelliğiyle tanımlamak için SYNC yanıtlarına şu dize alanlarını ekleyebilirsiniz:
Connectivity Standards Alliance (Alliance) tarafından verilen tedarikçi kimliği:
"matterOriginalVendorId": "0xfff1",Bir tedarikçinin ürününü benzersiz şekilde tanımlayan ürün tanımlayıcısı:
"matterOriginalProductId": "0x1234",Cihazın benzersiz tanımlayıcısı. Üreticiye özgü bir şekilde oluşturulur:
"matterUniqueId": "matter-device-id",
Bu dize alanlarını girerken varsa Matter
Tedarikçi ve Ürün Kimliklerinizi kullanın. Alliance üyesi değilseniz ve bu kimlikler size atanmadıysa matterOriginalVendorId ve matterOriginalProductId alanlarını boş bırakıp tanımlayıcı olarak matterUniqueId değerini girebilirsiniz.
Örnek SYNC yanıtı, bu alanların kullanımını gösterir:
{
"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",
}
]
}
]
}
}
Daha fazla bilgi için Cloud-to-cloud SYNC belgelerine bakın.
Cihaz ve özellik meta verileri
Home API'lerindeki cihazlar ve özellikler, uygulamadaki kullanıcı deneyimini yönetmeye yardımcı olabilecek meta verilerle ilişkilendirilir.
Home API'lerindeki her özellik, özelliğin online durumu ve konumu (yerel veya uzaktan yönlendirme) hakkında bilgi içeren bir sourceConnectivity özelliği içerir.
Cihazın birincil türünü alma
Bazı cihazlar, Home API'leri aracılığıyla birden fazla cihaz türü sunabilir. Kullanıcılara bir uygulamada cihazları için uygun seçeneklerin (ör. cihaz kontrolü ve önerilen otomasyonlar) sunulmasını sağlamak amacıyla bir cihazın birincil cihaz türünün ne olduğunu kontrol etmek faydalıdır.
Öncelikle type() kullanarak cihazın türlerini alın, ardından birincil türleri belirleyin:
val types = device.types().first() val primaryTypes = types.filter { it.metadata.isPrimaryType }
Bir özelliğin online olup olmadığını kontrol etme
Bir özelliğin bağlantısını kontrol etmek için connectivityState() yöntemini kullanın:
val onOffConnectivity = onOffTrait?.metadata?.sourceConnectivity?.connectivityState
Cihazın internet bağlantısı yoksa bazı özellikler (genellikle Google smart home özellikleri) çevrimdışı olarak gösterilebilir. Bunun nedeni, bu özelliklerin bulut tabanlı olması ve yerel yönlendirmeye sahip olmamasıdır.
Cihazın bağlantısını kontrol etme
Bazı cihazlar birden fazla cihaz türünü desteklediğinden, bir cihazın bağlantısı aslında cihaz türü düzeyinde kontrol edilir. Döndürülen durum, söz konusu cihazdaki tüm özelliklerin bağlantı durumlarının birleşimidir.
val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState
İnternet bağlantısı olmadığında karma cihaz türleri için PARTIALLY_ONLINE durumu görülebilir.
Yerel yönlendirme nedeniyle Matter standart özellik hâlâ çevrimiçi olabilir ancak bulut tabanlı özellikler çevrimdışı olur.
Cihazın IP adresini alma
Cihazın IP adresini bulmak için GeneralDiagnostics özelliğinin networkInterfaces özelliğini kullanın. Adresler, standart IPv4 veya IPv6 dizeleri olarak biçimlendirebileceğiniz bayt dizileri olarak döndürülür:
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()
Bir özelliğin ağ yönlendirmesini kontrol etme
Özelliğin konumu Home API'lerinde de kullanılabilir. dataSourceLocality, özelliğin uzaktan (bulut üzerinden), yerel olarak (yerel bir hub üzerinden) veya eşler arası (cihazdan cihaza doğrudan, hub olmadan) yönlendirilip yönlendirilmediğini gösterir.
Bilinmeyen yerleşim değeri UNSPECIFIED, örneğin bir uygulama başlatılırken ve cihaz bağlantısı için henüz bir hub'a veya sunucuya ulaşmamışken mümkündür. Bu cihazlara erişilemez ve komutlardan veya etkinliklerden gelen etkileşim istekleri başarısız olur. Bu tür cihazların nasıl ele alınacağını belirlemek istemciye bağlıdır.
val onOffLocality = onOffTrait?.metadata?.sourceConnectivity?.dataSourceLocality
Cihazın ağ yönlendirmesini kontrol etme
Bağlantı gibi yerellik de cihaz türü düzeyinde kontrol edilir. Döndürülen durum, o cihazdaki tüm özelliklerin yerelliğinin bir kombinasyonudur.
val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality
MIXED durumu, PARTIALLY_ONLINE bağlantısına benzer bir senaryoda görülebilir: Bazı özellikler bulut tabanlıyken diğerleri yereldir.
Cihazın adını değiştirme
Bir cihazın adını değiştirmek için setName() yöntemini çağırın:
mixerDevice.setName("Grendel")
Adlar, 60 Unicode kod noktası (karakter) sınırını aşarsa kısaltılır ve hata gösterilmez. Uzun adların işlenmesinden geliştiriciler sorumludur. Örneğin, adların kısaltılacağı konusunda kullanıcıları bilgilendirmek isteyip istemediklerine karar verebilirler.
Bir cihazın grup üyeliğini kontrol etme
Fiziksel bir cihaz, bir veya daha fazla cihaz grubuna ait olabilir. Bir cihazın hangi gruplara ait olduğunu görmek için cihazdaki GroupMembership özelliğini kontrol edin:
val groupIds = device.trait(GroupMembershipTrait)?.groupObjectIds.orEmpty()
for (groupId in groupIds) {
println("HomeAPI", "Device belongs to group: $groupId")
}
Bununla birlikte, bir DeviceGroup'e ait tüm üye cihazları, bir DeviceGroup üzerinde devices() akışını çağırarak gözlemleyebilirsiniz:
group.devices(enableMultipartDevices = true).collect { members ->
println("HomeAPI", "Group contains ${members.size} devices")
}
Bir DeviceGroup tarafından desteklenen cihaz türlerini incelemek ve gruba tek bir varlık olarak komut göndermek için Cihaz grubunu kontrol etme başlıklı makaleyi inceleyin.