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 On/Off özelliğini ve On/Off Plug-in Unit 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'ı yakalamak için try-catch bloğunu kullanmanızı öneririz.
HomeException ile ilgili işlem yaparken neyin yanlış gittiğini öğrenmek için
error.code ve
error.message alanlarını kontrol edin. Alt hata kodları da olabilir.
getSubErrorCodes() yöntemini çağırıp sonucu kontrol edin.
İşlenmemiş 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
Yapı mevcutken devices() çağrısı, bu yapıdan erişebileceğiniz cihazların Flow'unu 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şilebilir ve cihaza desteklenen komutlar gönderilebilir.
Cihaz durumunu okuma
Cihazın OnOff özelliğinin Açık/Kapalı özelliğinden kontrol edilmesine dair bir örneğe bakalım. Bu özelliğin OnOff olarak tanımlandığı Home API'leri ö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 raporlanmadığı durumlarda abonelikler aracılığıyla alınan bir durumu hedef cihazda geçersiz kılma olanağı sağlar.
Durumun doğru şekilde raporlanmayabileceğ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 ardından ö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/Kapama 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 listesini almak için Açma/Kapatma özelliğine sahip olanları listeleyin:
// Get all devices that support OnOff val onOffDevices: Flow<List<HomeDevice>> = home.devices().map { devices -> devices.filter { it.has(OnOff) } }
Ev 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.
Ev 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ıtına ekleyebilirsiniz:
Connectivity Standards Alliance (CSA) tarafından verilen tedarikçi 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 için üreticiye özel bir şekilde oluşturulan benzersiz tanımlayıcı:
"matterUniqueId": "matter-device-id",
Bu dize alanlarını girerken varsa Matter
tedarikçi ve ürün kimliklerinizi kullanın. CSA üyesi değilseniz ve bu kimlikler size atanmadıysa matterOriginalVendorId ve matterOriginalProductId alanlarını boş bırakabilir ve 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, uygulamadaki kullanıcı deneyimini yönetmeye yardımcı olabilecek meta veriler bulunur.
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 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ı 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, cihazda 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 offline olur.
Bir özelliğin ağ yönlendirmesini kontrol etme
Bir özelliğin yerel ayarı, Home API'lerinde de kullanılabilir. dataSourceLocality, özelliğin uzaktan (bulut üzerinden), yerel olarak (yerel bir hub üzerinden) veya cihazdan cihaza (doğrudan cihazdan cihaza, hub olmadan) yönlendirilip yönlendirilmediğini gösterir.
Bilinmeyen yerel değer UNSPECIFIED, ö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 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 ele alınacağına istemci karar verir.
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ı durumu 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 kesilir ve hata verilmez. Geliştiriciler, uzun adları işlemeyle sorumludur ve örneğin, adların kısaltılacağı konusunda kullanıcıları bilgilendirmek isteyip istemediklerine karar verebilirler.