Cihazlara ve cihaz meta verilerine erişme

Cihaz API'lerine Home API'leri üzerinden erişilebilir. Aşağıdaki 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 cihaz API'leriyle kullanmak için ayrı ayrı içe aktarmaları 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 Veri modeli başlıklı makaleyi inceleyin.

Hata işleme

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

HomeException ile çalışırken 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 Cihazlara komut gönderme başlıklı makaleyi inceleyin.

Örnek aramalar

Cihazların listesini alma

Yapı mevcut olduğunda devices() çağrısı, bu yapıdan erişebileceğiniz cihazların akışını 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 desteklenen komutlar cihaza gönderilebilir.

Cihaz durumunu okuma

Cihazın Açma/Kapatma özelliğinden OnOff özelliğini kontrol etme örneğine bakalım. Bu özelliğin OnOff olarak tanımlandığı Home APIs ö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()!!

Kotlin flow işlevi hakkında daha fazla bilgi edinmek için distinctUntilChanged bölümüne bakın.

Özellik aboneliğinde durumu geçersiz kılma

TraitStateInvalidation arayüzü, durumun doğru şekilde raporlanmadığı durumlarda hedef cihaza abonelikler aracılığıyla alınan bir durumu geçersiz kılma olanağı sunar. Durumun doğru şekilde raporlanmadığı durumlara örnek olarak, Matter özelliklerinde "C" kalitesine sahip özellikler kullanılması veya beklenmedik bir şekilde soruna neden olan bir cihaz uygulaması verilebilir.

Bu API, mevcut özellik durumunu zorunlu olarak okur ve sonucu mevcut özellik akışları aracılığıyla döndürür.

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

val generalDiagnosticsTrait = device.trait(GeneralDiagnostics).first()
generalDiagnosticsTrait.forceRead()

Cihaz türü özelliklerinin listesini alma

Cihaz türleri, bir cihazı işlevsel parçalarına (Matter'teki uç noktalar gibi) ayırdığından, özellikleri okumak için giriş noktası olarak kullanılmalıdır.

Ayrıca, bir cihazda her ikisi de aynı özelliğe sahip olabilecek iki cihaz türü varsa özellik çakışmalarını da hesaba katarlar. Örneğin, bir cihaz hem hoparlör hem de kısılabilir ışıksa iki açma/kapatma ve iki seviye kontrolü özelliğine sahiptir.

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()

Bir cihazda aynı ada sahip iki özellik olduğunda da özellik çakışması meydana gelebilir. Örneğin, onOff standart OnOff özelliğinin bir örneğini veya üretici tanımlı bir OnOff özelliğinin bir örneğini referans alabilir. Hangi özelliğin kastedildiğiyle ilgili olası belirsizlikleri ortadan kaldırmak için, bir cihaz aracılığıyla referans verilen Trait örneğinin önüne uygun bir ad alanı gelmelidir. Standart özellikler (yani Matter standart kümelerine benzer özellikler) 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 özgü 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 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'lerde 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'lerde 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}")

Buluttan buluta aktarım yapan cihazları belirleme

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 SYNC yanıtlarına aşağıdaki dize alanlarını ekleyebilirsiniz:

• Connectivity Standards Alliance (CSA) tarafından verilen tedarikçi firma kimliği: "matterOriginalVendorId": "0xfff1",

• Tedarikçi firmanın bir ürününü benzersiz şekilde tanımlayan ürün tanımlayıcısı: "matterOriginalProductId": "0x1234",

• Cihazın üreticiye özgü bir şekilde oluşturulan benzersiz tanımlayıcısı: "matterUniqueId": "matter-device-id",

Bu dize alanlarına girerken, varsa Mattersağlayıcı ve ürün kimliklerinizi kullanın. CSA üyesi değilseniz ve bu kimlikler size atanmamışsa matterOriginalVendorId ve matterOriginalProductId alanlarını boş bırakabilir ve tanımlayıcısı 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 göz atın.

Cihaz ve özellik meta verileri

Home API'lerindeki cihazlar ve özelliklerle ilişkili meta veriler, uygulamadaki kullanıcı deneyimini yönetmenize yardımcı olabilir.

Home API'lerindeki her özellik, özelliğin çevrimiçi durumu ve yerelliği (yerel veya uzak yönlendirme) hakkında bilgi içeren bir sourceConnectivity mülkü 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ına uygun seçeneklerin (ör. cihaz kontrolü ve önerilen otomasyonlar) bir uygulamada sunulmasını sağlamak için cihazın birincil cihaz türünü kontrol etmek faydalıdır.

Öncelikle type() kullanarak cihazın türlerini alın, ardından birincil türün hangisi olduğunu belirleyin:

val types = device.types().first()
val primaryType = types.first { it.metadata.isPrimaryType }

Bir özelliğin internete bağlı 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.

Bir cihazın bağlantısını kontrol etme

Bazı cihazlar birden fazla cihaz türünü desteklediği için 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 bir birleşimidir.

val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState

Karışık cihaz türlerinde internet bağlantısı olmadığında PARTIALLY_ONLINE durumu gözlemlenebilir. Matter standart özellikleri yerel yönlendirme nedeniyle hâlâ online olabilir ancak bulut tabanlı özellikler çevrimdışı olur.

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ı (doğrudan cihazdan cihaza, hub olmadan) yönlendirilip yönlendirilmediğini belirtir.

Bilinmeyen yerellik değeri UNSPECIFIED, örneğin bir uygulama başlatılırken ve henüz cihaz bağlantısı için bir merkeze veya sunucuya ulaşmamışken görülebilir. 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

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 yerelliğinin bir kombinasyonudur.

val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality

PARTIALLY_ONLINE bağlantısı ile benzer bir senaryoda MIXED durumu gözlemlenebilir: Bazı özellikler bulut tabanlıyken diğerleri yereldir.

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: