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

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'te 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 do-catch bloğu kullanmanızı öneririz.

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

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

Home nesnesine referans vererek erişilebilir cihazların Query listesini almak için devices() işlevini çağırın. Her cihaz meta verisi değişikliğinde Home'un mevcut durumunu yansıtan bir Set yayan Query's batched() yöntemini çağırın. Alternatif olarak, mevcut cihazların anlık görüntüsünü almak için Query.list() numarasını arayın. Bu, batched() akışına abone olan ve yayınlanan ilk değeri döndüren bir kolaylık yöntemidir. Query.stream() Cihaz meta verilerinde (ör. ad, oda veya yapı) değişiklik olduğunda yeni değerler yayan bir akış oluşturur. Bu özellik, dahili olarak batched() kullanır ve yalnızca değiştirilen özellikleri yayınlar.

// 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 cihaza desteklenen komutlar gönderilebilir.

Cihaz türlerini alma

Bir cihazla ilişkili cihaz türlerini almak için cihazın types özelliğini okuyun. Bu özellik, 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 bu türün işleyicisini alabilirsiniz:

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

Cihaz, belirtilen türü desteklemiyorsa nil değerini döndürür.

DeviceTypeController.subscribeAll() numaralı telefonu arayarak Publisher DeviceTypeCollection alı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, özellikleri okumak için giriş noktasıdır. Cihazı işlevsel parçalarına (ör. Matter'daki uç noktalar) ayırır.

Ayrıca, bir cihazın aynı özelliğe sahip olabilecek iki cihaz türü içermesi 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.

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 her cihaz türündeki iki özellik koleksiyonundan birini kullanarak bir özelliğe referans verin.

Standart özellikler (yani Matter standart kümelerine benzer olanlar) için matterTraits kullanın. Örneğin, kısılabilir ışık 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.traits[Google.DoorbellPressTrait.self]
}

Üreticiye özel bir özelliğe erişmek için traits property aracılığıyla referans verin ancak üreticinin paket adıyla başlayın:

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/Kapama özelliğinden 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 yinelemeniz gerekir. Örneğin, evdeki tüm cihazların listesini almak için On/Off (Açma/Kapama) özelliğini kullanın:

// Get all light devices that support levelControl
var levelControlDevices: [HomeDevice] = []
let 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)
    }
  }
}

Ev API'lerinde kullanılabilen özelliklerin tam listesi için iOS'te ö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 ışığı temsil edebilecek dört farklı cihaz türü vardır. Bu nedenle, bir evdeki üst düzey cihaz türünün kapsamlı bir görünümünü elde etmek için birden fazla cihaz türü dahil edilmelidir.

Cihaz türlerinin ve Home API'lerinde kullanılabilen ö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 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 için üreticiye özel bir şekilde oluşturulan benzersiz tanımlayıcı: "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 meta veriler bulunur. 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 uygulamada cihazları için uygun seçeneklerin (ör. cihaz kontrolü ve önerilen otomasyonlar) sunulmasını sağlamak amacıyla cihaz türünün, cihazın birincil türü olup olmadığını kontrol etmek faydalı olur.

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 internette olup olmadığını kontrol etme

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

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

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.

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

İnternet bağlantısı olmadığında karışık cihaz türleri söz konusuysa partiallyOnline durumu gözlemlenebilir. Matter standart özellikler, yerel yönlendirme nedeniyle hâlâ çevrimiçi olabilir ancak bulut tabanlı özellikler çevrimdışı 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.

Ö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 olabilir. 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.

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 yerel birleşimidir.

let lightLocality =
  dimmableLightDeviceType.metadata.sourceConnectivity.dataSourceLocality

mixed bağlantısıyla benzer bir senaryoda partiallyOnline 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:

let updatedDevice = try await theDevice.setName("new device name")

Bir cihazın adı değiştirildiğinde orijinal HomeDevice yapısı aynı kalır ve değişiklik, döndürülen güncellenmiş HomeDevice nesnesine yansıtılır.

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 edindikten sonra aşağıdaki API'lere bu kimlik üzerinden erişebilirsiniz: