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

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Cihaz API'lerine iOS için Home API'leri üzerinden erişilebilir. Aşağıdaki paketleri uygulamanıza aktarın:

import GoogleHomeSDK
import GoogleHomeTypes

Daha fazla bilgi için iOS'teki veri modeli başlıklı makaleyi inceleyin.

Hata işleme

Home API'lerindeki bazı yöntemler HomeError oluşturur. Bu nedenle, bu çağrılarda HomeError yakalamak için bir do-catch bloğu kullanmanızı öneririz.

HomeError ile çalışırken neyin yanlış gittiğini öğrenmek için code ve message alanlarını kontrol edin.

İşlenmemiş hatalar, 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

Erişilebilir cihazların Query listesini almak için Home nesnesine referans vererek devices()'i çağırın. Her cihaz meta veri değişikliğinde Home'un mevcut durumunu yansıtan bir Set yayan Query'ın batched() yöntemini çağırın. Alternatif olarak, mevcut cihazların anlık görüntüsünü almak için Query.list() numaralı telefonu arayın. Bu, batched() akışına abone olan ve ilk yayınlanan değeri döndüren bir kolaylık yöntemidir. Query.stream(), cihaz meta verilerindeki ad, oda veya yapı gibi değişikliklerle ilgili yeni değerler yayınlayan bir akış oluşturur. Bu işlemde dahili olarak batched() kullanılır ve yalnızca değiştirilen özellikler yayınlanır.

// Get a list of all devices accessible to the user
let homeDevices = try await self.home.devices().list()

Buradan her cihazın durumuna erişilebilir ve desteklenen komutlar cihaza gönderilebilir.

Cihazın türlerini alma

Bir cihazla ilişkili cihaz türlerini almak için cihazın types mülkünü okuyun. Bu mülk, DeviceTypeController döndürür.

Belirli bir cihaz türüyle ilgili güncellemelere abone olmak için DeviceTypeController.subscribe(_:) numaralı telefonu arayın:

let devices = try await self.home.devices().list()
if let device = devices.first(where: { $0.id == myDeviceId }) {
  var receivedUpdate1 = false
  var receivedUpdate2 = false
  device.types.subscribe(OnOffLightDeviceType.self)
    .assertNoFailure()
    .sink { device in
      if !receivedUpdate1 {
        receivedUpdate1 = true
        Task {
          try await device.matterTraits.onOffTrait?.on()
        }
        return
      }
      if !receivedUpdate2 {
        receivedUpdate2 = true
        return
      }
      fatalError("Received unexpected update")
    }
}

Cihaz belirtilen cihaz türünü desteklemiyorsa hemen tamamlanan bir Empty Publisher döndürür.

Cihaz belirli bir cihaz türünü destekliyorsa get() işlevini çağırarak söz konusu türün adını alabilirsiniz:

if let device = devices.first(where: { $0.id == myDeviceId }) {
  let deviceType = await device.types.get(OnOffLightDeviceType.self)
}

Cihaz belirtilen türü desteklemiyorsa nil döndürülür.

DeviceTypeCollection hakkında Publisher almak için DeviceTypeController.subscribeAll() numaralı telefonu arayın. Bu sınıf, cihazın belirli bir cihaz türüne sahip olup olmadığını kontrol etmenize olanak tanır:

if let device = devices.first(where: { $0.id == myDeviceId }) {
  device.types.subscribeAll()
    .assertNoFailure()
    .sink { types in
      let lightDeviceType = types[OnOffLightDeviceType.self]
      let fanDeviceType = types[FanDeviceType.self]
    }
}

Cihaz türü özelliği alma

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

Ayrıca, bir cihazda her ikisi de aynı özelliğe sahip olabilecek iki cihaz türü bulunması durumunda ö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.

Bir cihazda aynı ada sahip iki özellik olduğunda başka bir ö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 her cihaz türünde bulunan iki özellik koleksiyonundan birini kullanarak bir özelliğe referans verin.

Standart özellikler (yani Matter standart kümelerine benzer özellikler) için matterTraits kullanın. Örneğin, Dimmable Light cihaz türü için belirli bir özelliği almak istiyorsanız:

if let dimmableLightDeviceType =
  await device.types.get(DimmableLightDeviceType.self)
{
  // Accessing standard trait on the type.
  let levelControlTrait =
    dimmableLightDeviceType.matterTraits.levelControlTrait.self
}

Google özellikleri için googleTraits'ü kullanın:

if let doorbellDeviceType = await device.types.get(GoogleDoorbellDeviceType.self) {
  // Accessing Google trait on the type.
  let doorbellPressTrait =
    doorbellDeviceType.googleTraits.doorbellPressTrait.self
}

Üreticiye özgü bir özelliğe erişmek için traits mülkü aracılığıyla bu özelliğe referans verin ancak bu referansın önüne üreticinin paket adını ekleyin:

let deviceType = await device1?.types.get(OnOffLightDeviceType.self)
// Accessing custom trait on the type.
if let spinnerTrait = deviceType?.traits[ExampleOrganization.SpinnerTrait.self] {
  let rpmVal = spinnerTrait.attributes.rpm
}

Cihaz durumunu okuma

Cihazın Açma/Kapatma özelliğindeki OnOff özelliğini kontrol etme örneğine göz atın:

let lightDevices = devices.filter {
  $0.types.contains(OnOffLightDeviceType.self)
}
let light1 = lightDevices.first
let lightDeviceTypeOptional = await light1?.types.get(OnOffLightDeviceType.self)
if let onOffTrait = lightDeviceTypeOptional?.matterTraits.onOffTrait {
  let onOffVal = onOffTrait.attributes.onOff
}

Belirli bir özelliğe sahip cihazların listesini alma

Belirli bir özelliğe sahip cihazların listesini almak için cihazları, her cihazın cihaz türlerini ve her cihaz türünün özelliklerini iterasyonla incelemeniz gerekir. Örneğin, evdeki tüm cihazların Açık/Kapalı özelliğine sahip olduğu cihazların listesini almak için:

// Get all light devices that support levelControl
var levelControlDevices: [HomeDevice] = []
var allDevices = try await home.devices().list()
for device in allDevices {
  if let deviceType = await device.types.get(OnOffLightDeviceType.self) {
    if deviceType.traits.contains(Matter.LevelControlTrait.self) {
      levelControlDevices.append(device)
    }
  }
}

Home API'lerde kullanılabilen özelliklerin tam listesi için iOS'teki özellik dizini başlıklı makaleyi inceleyin.

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)
let lightDevices =
  try await self.home.devices().list().compactMap {
    $0.types.contains(DimmableLightDeviceType.self)
      || $0.types.contains(OnOffLightDeviceType.self)
      || $0.types.contains(ColorTemperatureLightDeviceType.self)
      || $0.types.contains(ExtendedColorLightDeviceType.self)
  }

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 bir ışığı temsil edebilecek dört farklı cihaz türü vardır. Bu nedenle, bir evdeki cihaz türünün üst düzey bir görünümünü elde etmek için birden fazla cihaz türü dahil edilmelidir.

Home API'lerde kullanılabilen cihaz türlerinin ve özelliklerinin tam listesi için iOS'te desteklenen cihaz türleri başlıklı makaleyi inceleyin.

Bir cihazın satıcı adını, satıcı kimliğini veya ürün kimliğini alma

BasicInformationTrait özelliği; tedarikçi kimliği, ürün kimliği, ürün adı ve cihazın seri numarası gibi bilgileri içerir:

guard
  let vendorName =
    basicInfoTrait.attributes.vendorName
else {
  fatalError("Failed to get vendorName")
}
guard
  let vendorID =
    basicInfoTrait.attributes.vendorID
else {
  fatalError("Failed to get vendorID")
}
guard
  let productID =
    basicInfoTrait.attributes.productID
else {
  fatalError("Failed to get 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 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ını girerken varsa Matter sağ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ı 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 dokümanlarına 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 türünün cihazın birincil türü olup olmadığını kontrol etmek faydalıdır.

if let deviceType =
  await device?.types.get(HumiditySensorDeviceType.self)
{
  if deviceType.metadata.isPrimaryType {
    print("Humidity Sensor is the primary type on this device.")
  } else {
    print("Humidity Sensor isn't the primary type on this device.")
  }
}

Bir özelliğin internete bağlı olup olmadığını kontrol etme

Bir özelliğin bağlantısını kontrol etmek için connectivityState mülkünü okuyun:

let levelControlConnectivity =
  levelControlTrait.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.

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

Karışık cihaz türlerinde internet bağlantısı olmadığında partiallyOnline 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 aittir.

let levelControlLocality =
  levelControlTrait.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.

let lightLocality =
  dimmableLightDeviceType.metadata.sourceConnectivity.dataSourceLocality

mixed durumu, partiallyOnline bağlantısına benzer bir senaryoda gözlemlenebilir: Bazı özellikler bulut tabanlıyken bazıları yereldir.

API listesi

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

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