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
Belirli cihaz türlerini veya özelliklerini Device API'lerle kullanmak için bunların ayrı ayrı içe aktarılması gerekir.
Örneğin, Matter Açma/Kapama özelliğini ve Açma/Kapama 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'deki veri modeli başlıklı makaleyi inceleyin.
Hata işleme
Ev API'lerindeki herhangi bir yöntem
HomeException oluşturabilir. Bu nedenle, tüm çağrılarda HomeException'i yakalamak için try-catch bloğunu kullanmanızı öneririz.
HomeException işlenirken 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ın ve sonucu kontrol edin.
İşlenmeyen istisnalar, uygulamanızın kilitlenmesine neden olur.
Daha fazla bilgi için Hata işleme başlıklı makaleyi inceleyin.
Örnek için Cihaza komut gönderme başlıklı makaleyi inceleyin.
Örnek görüşmeler
Cihaz listesini 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üyle birlikte, 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 OnOff özelliğinin Açma/Kapama özelliğinden kontrol edilmesine ilişkin bir örneğe göz atın. Bu özelliğin OnOff olarak tanımlandığı Home APIs özellik veri modelini kullanarak, özellik verilerini cihaz türünün standardTraits sınıfı üzerinden 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()!!
Kotlin akış işlevi hakkında daha fazla bilgi edinmek için
distinctUntilChanged
bölümüne bakın.
Bir özellik aboneliğinde durumu geçersiz kılma
TraitStateInvalidation arayüzü, durumun doğru şekilde bildirilmediği durumlarda abonelikler aracılığıyla alınan bir durumu hedef cihazda geçersiz kılma olanağı sağlar.
Durumun doğru şekilde raporlanamayabileceği durumlara örnek olarak, "C" kalitesindeki Matter özelliklerinde özelliklerin kullanılması veya soruna beklenmedik şekilde 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 ve özellik üzerinde 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, özellikleri okumak için giriş noktası olarak kullanılmalıdır. Çünkü cihazı işlevsel parçalarına (ör. Matter içindeki uç noktalar) ayırırlar.
Ayrıca, bir cihazda aynı özelliğe sahip olabilecek iki cihaz türü bulunması durumunda özellik çakışmalarını da hesaba katarlar. Örneğin, hem hoparlör hem de kısılabilir ışık olan bir cihazda iki Açma/Kapatma ve iki Seviye Kontrolü özelliği bulunur.
Kısılabilir Işık cihaz türü için kullanılabilen özelliklerin listesini almak üzere:
// 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 meydana gelebilir. Ö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 amaçlandığıyla ilgili olası belirsizlikleri ortadan kaldırmak için cihaz üzerinden referans verilen bir 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 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, evdeki tüm cihazların Açma/Kapatma özelliğine sahip olduğu bir liste 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
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 bir 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, ışığı temsil edebilecek dört farklı cihaz türü vardır. Bu nedenle, bir evdeki daha üst düzey cihaz türü hakkında kapsamlı bir görünüm 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; tedarikçi kimliği, ürün kimliği, ürün adı ve cihazın 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 BasicInformation özelliği aracılığıyla Cloud-to-cloud cihazlarınızı tanımlamak için bu dize alanlarını SYNC yanıtlarına ekleyebilirsiniz:
Connectivity Standards Alliance (Alliance) tarafından verilen sağlayıcı kimliği:
"matterOriginalVendorId": "0xfff1",Bir satıcının ürününü benzersiz şekilde tanımlayan bir ürün tanımlayıcısı:
"matterOriginalProductId": "0x1234",Cihazın benzersiz tanımlayıcısı. Üreticiye özel 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ırakabilir, tanımlayıcı olarak matterUniqueId değerini girebilirsiniz.
Örnek SYNC yanıtında bu alanların kullanımı gösterilmektedir:
{
"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 özelliklerle ilişkili meta veriler vardır. Bu meta veriler, uygulamadaki kullanıcı deneyiminin yönetilmesine yardımcı olabilir.
Home API'lerindeki her özellik, bir özelliğin online durumu ve yerelliği (yerel veya uzaktan yönlendirme) hakkında bilgi içeren bir sourceConnectivity özelliği içerir.
Bir cihazın birincil türünü alma
Bazı cihazlar, Home API'leri aracılığıyla birden fazla cihaz türü sunabilir. Kullanıcılara cihazları için uygulamada (ör. cihaz kontrolü ve önerilen otomasyonlar) uygun seçeneklerin sunulmasını sağlamak amacıyla cihazın birincil cihaz türünün ne olduğunu kontrol etmek faydalı olur.
Ö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 internette 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
Genellikle Google smart home özellikleri olan bazı özellikler, cihazın internet bağlantısı yoksa çevrimdışı gösterilebilir. Bunun nedeni, bu özelliklerin bulut tabanlı olması ve yerel yönlendirmeye sahip olmamasıdır.
Bir cihazın bağlantısını kontrol etme
Bir cihazın bağlantısı aslında cihaz türü düzeyinde kontrol edilir. Çünkü bazı cihazlar birden fazla cihaz türünü destekler. 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 karışık cihaz türleri söz konusuysa PARTIALLY_ONLINE durumu gözlemlenebilir.
Matter standart özellikleri, yerel yönlendirme nedeniyle hâlâ online 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
Bir özelliğin yerelliği 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.
Örneğin, bir uygulama başlatılırken ve henüz cihaz bağlantısı için bir hub'a veya sunucuya ulaşmamışken bilinmeyen yerel değer UNSPECIFIED mümkündür. Bu cihazlara ulaşılamaz ve komutlardan veya etkinliklerden gelen etkileşim istekleri başarısız olur. Bu tür cihazların nasıl işleneceğini belirlemek istemciye bağlıdır.
val onOffLocality = onOffTrait?.metadata?.sourceConnectivity?.dataSourceLocality
Bir cihazın ağ yönlendirmesini kontrol etme
Bağlantı gibi yerellik de cihaz türü düzeyinde kontrol edilir. Döndürülen durum, söz konusu cihazdaki tüm özelliklerin yerel ayarlarının birleşimidir.
val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality
MIXED'da da benzer bir senaryoda PARTIALLY_ONLINE bağlantısı gibi bir durum gözlemlenebilir: Bazı özellikler bulut tabanlıyken bazıları yereldir.
Cihaz 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 verilmez. Geliştiriciler, uzun adları işlemeyle yükümlüdür. Örneğin, kullanıcıları adların kısaltılacağı konusunda bilgilendirmek isteyip istemediklerine karar verebilirler.