Android için cihazlara ve cihaz meta verilerine erişme

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

Home API'lerindeki tüm yöntemler HomeException istisnası oluşturabilir. Bu nedenle, tüm çağrılarda HomeException istisnasını yakalamak için try-catch bloğu kullanmanızı öneririz.

HomeException işlenirken neyin yanlış gittiğini öğrenmek için code ve message alanlarını kontrol edin.

İşlenmemiş 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 görüşmeler

Cihaz listesini alma

Yapı kullanılabilir olduğunda, devices() çağrısı, bu yapıdan erişebileceğiniz bir cihaz akışı 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 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 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 akışları aracılığıyla sonucu döndürür ve mevcut özellik durumunun zorunlu olarak okunmasını sağlar.

Özelliği alın, ardından özellik üzerinde forceRead çalıştırın:

val generalDiagnosticsTrait = device.trait(GeneralDiagnostics).first()
generalDiagnosticsTrait.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'daki 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 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) } }

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ıtları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ın benzersiz tanımlayıcısı. Üreticiye özel bir şekilde oluşturulur: "matterUniqueId": "matter-device-id",

Bu dize alanlarını girerken varsa Matter satıcı 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 sağlayabilirsiniz.

Ö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 bir uygulamada cihazlarıyla ilgili uygun seçeneklerin (ör. cihaz kontrolü ve önerilen otomasyonlar) sunulmasını sağlamak için 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

Bazı özellikler (genellikle Google smart home özellikleri), cihazda internet bağlantısı yoksa çevrimdışı olarak 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

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 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 bölge değeri 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 yerleşim biriminin birleşimidir.

val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality

MIXED bağlantısında da benzer bir durum gözlemlenebilir: Bazı özellikler bulut tabanlıyken bazıları yereldir.PARTIALLY_ONLINE

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.

API listesi

Home örneği oluşturulduktan sonra aşağıdaki Cihaz API'lerine bu örnek üzerinden erişilebilir:

HomeDevice aldıktan sonra aşağıdaki API'lere erişebilirsiniz: