دسترسی به دستگاه‌ها و فراداده دستگاه برای iOS

APIهای دستگاه ممکن است از طریق APIهای Home برای iOS قابل دسترسی باشند. بسته های زیر را به برنامه خود وارد کنید:

import GoogleHomeSDK
import GoogleHomeTypes

برای اطلاعات بیشتر، مدل داده در iOS را ببینید.

رسیدگی به خطا

برخی از روش‌ها در APIهای Home یک HomeError ایجاد می‌کنند، بنابراین توصیه می‌کنیم از بلوک do-catch برای دریافت HomeError در آن تماس‌ها استفاده کنید.

هنگام رسیدگی به HomeError ، فیلدهای code و message آن را بررسی کنید تا بدانید چه مشکلی پیش آمده است.

هر گونه خطای کنترل نشده باعث از کار افتادن برنامه شما می شود.

برای اطلاعات بیشتر، رسیدگی به خطا را ببینید.

برای مثال به ارسال فرمان به دستگاه مراجعه کنید.

تماس های نمونه

لیستی از دستگاه ها را دریافت کنید

با ارجاع به شی Home ، devices() را فراخوانی کنید تا یک Query از دستگاه های قابل دسترسی دریافت کنید. متد batched() Query را فراخوانی کنید، که مجموعه‌ای را منتشر می‌کند که وضعیت فعلی خانه را با هر تغییر ابرداده دستگاه منعکس می‌کند. یا با Query.list() تماس بگیرید تا یک عکس فوری از دستگاه های موجود دریافت کنید. این یک روش راحت است که در جریان batched() مشترک می شود و اولین مقدار منتشر شده را برمی گرداند. Query.stream() جریانی تولید می کند که مقادیر جدیدی را در تغییرات فراداده دستگاه مانند نام، اتاق یا ساختار آن منتشر می کند. در داخل، از batched() استفاده می کند و فقط ویژگی های تغییر یافته را منتشر می کند.

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

از آنجا، وضعیت های هر دستگاه قابل دسترسی است و دستورات پشتیبانی شده را می توان به دستگاه ارسال کرد.

انواع دستگاه را دریافت کنید

برای دریافت انواع دستگاه مرتبط با یک دستگاه، ویژگی types دستگاه را بخوانید که یک DeviceTypeController را برمی‌گرداند.

با DeviceTypeController.subscribe(_:) تماس بگیرید تا در به روز رسانی های یک نوع دستگاه خاص مشترک شوید:

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")
    }
}

اگر دستگاه از نوع دستگاه مشخص شده پشتیبانی نمی کند، یک Empty Publisher برمی گرداند که بلافاصله تکمیل می شود.

اگر دستگاه از نوع دستگاه خاصی پشتیبانی می کند، می توانید با فراخوانی get() یک دسته برای آن نوع دریافت کنید:

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

اگر دستگاه از نوع مشخص شده پشتیبانی نکند، nil برمی‌گرداند.

با DeviceTypeController.subscribeAll() تماس بگیرید تا یک Publisher از DeviceTypeCollection دریافت کنید. این کلاس به شما امکان می دهد بررسی کنید که آیا دستگاه دارای یک نوع دستگاه خاص است یا خیر:

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]
    }
}

یک ویژگی نوع دستگاه دریافت کنید

انواع دستگاه ها نقطه ورود برای خواندن صفات هستند، زیرا آنها یک دستگاه را به قطعات کاربردی آن تجزیه می کنند (مانند نقاط پایانی در Matter ).

آنها همچنین برای برخوردهای صفت در صورتی که یک دستگاه دارای دو نوع دستگاه باشد، که هر دو ممکن است دارای یک ویژگی باشند، حساب می کنند. به عنوان مثال، اگر دستگاهی هم اسپیکر و هم نور کم نور باشد، دو ویژگی روشن/خاموش و دو ویژگی کنترل سطح دارد.

نوع دیگری از برخورد صفت زمانی رخ می دهد که یک دستگاه دارای دو ویژگی با نام یکسان باشد. برای مثال، onOff می‌تواند به نمونه‌ای از ویژگی استاندارد OnOff اشاره کند، یا می‌تواند به نمونه‌ای از ویژگی OnOff تعریف‌شده توسط سازنده اشاره کند. برای از بین بردن هرگونه ابهام احتمالی در مورد اینکه کدام ویژگی مورد نظر است، یک ویژگی را از طریق یکی از دو مجموعه ویژگی در هر نوع دستگاه ارجاع دهید.

برای صفات استاندارد، یعنی آنهایی که مشابه خوشه های استاندارد Matter هستند، از matterTraits استفاده کنید. به عنوان مثال، برای به دست آوردن یک ویژگی خاص برای نوع دستگاه نور کم نور:

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

برای ویژگی های گوگل، از googleTraits استفاده کنید:

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

برای دسترسی به یک ویژگی خاص سازنده، از طریق ویژگی traits به آن ارجاع دهید، اما نام بسته سازنده را پیشگفتار کنید:

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
}

وضعیت دستگاه را بخوانید

به این مثال از بررسی ویژگی OnOff از ویژگی On/Off دستگاه نگاه کنید:

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
}

لیستی از دستگاه هایی با یک ویژگی خاص را دریافت کنید

برای دریافت فهرستی از دستگاه‌هایی که ویژگی خاصی دارند، باید دستگاه‌ها، انواع دستگاه‌های هر دستگاه و ویژگی‌های هر نوع دستگاه را تکرار کنید. به عنوان مثال، برای دریافت لیستی از دستگاه‌های موجود در خانه که همگی دارای ویژگی روشن/خاموش هستند:

// 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 به فهرست Trait در iOS مراجعه کنید.

لیستی از دستگاه هایی با انواع دستگاه های مشابه دریافت کنید

برای دریافت لیستی از دستگاه هایی که نشان دهنده تمام چراغ های یک خانه هستند:

// 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)
  }

چندین نوع دستگاه در APIهای Home وجود دارد که می تواند یک نوع دستگاه اصلی را نشان دهد. به عنوان مثال، نوع دستگاه "Light" وجود ندارد. در عوض، چهار نوع دستگاه مختلف وجود دارد که می توانند نور را نشان دهند، همانطور که در مثال قبل نشان داده شده است. به این ترتیب، برای به دست آوردن یک دید جامع از نوع دستگاه سطح بالاتر در یک خانه، باید چندین نوع دستگاه گنجانده شود.

برای لیست کامل انواع دستگاه ها و ویژگی های آنها که در API های Home در دسترس هستند ، انواع دستگاه های پشتیبانی شده را در iOS ببینید.

نام فروشنده، شناسه فروشنده یا شناسه محصول را برای یک دستگاه دریافت کنید

ویژگی BasicInformationTrait شامل اطلاعاتی مانند شناسه فروشنده، شناسه محصول، نام محصول و شماره سریال یک دستگاه است:

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")
}

شناسایی دستگاه ابر به ابر برای سازندگان دستگاه

اگر سازنده دستگاه هستید و دستگاه‌های Cloud-to-cloud می‌سازید، به منظور شناسایی دستگاه‌های Cloud-to-cloud خود از طریق ویژگی BasicInformation ، می‌توانید این فیلدهای رشته‌ای را در پاسخ SYNC آن‌ها قرار دهید:

• اتحادیه استانداردهای اتصال (CSA) شناسه فروشنده صادر کرد: "matterOriginalVendorId": "0xfff1",

• یک شناسه محصول که به طور منحصربه‌فرد محصول یک فروشنده را شناسایی می‌کند: "matterOriginalProductId": "0x1234",

• یک شناسه منحصر به فرد برای دستگاه، که به روشی خاص سازنده ساخته شده است: "matterUniqueId": "matter-device-id",

هنگام وارد کردن این فیلدهای رشته، از Matter فروشنده و محصول خود در صورت داشتن آنها استفاده کنید. اگر عضو CSA نیستید و این شناسه ها به شما اختصاص داده نشده است، می توانید فیلدهای matterOriginalVendorId و matterOriginalProductId را خالی بگذارید و matterUniqueId به عنوان شناسه ارائه کنید.

نمونه پاسخ SYNC استفاده از این فیلدها را نشان می دهد:

{
  "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",
          }
        ]
      }
    ]
  }
}

برای اطلاعات بیشتر، به مستندات Cloud-to-cloud SYNC مراجعه کنید.

فراداده دستگاه و ویژگی

دستگاه‌ها و ویژگی‌ها در Home API دارای ابرداده‌های مرتبط با آن‌ها هستند که می‌تواند به مدیریت تجربه کاربر در یک برنامه کمک کند.

هر ویژگی در APIهای Home حاوی یک ویژگی sourceConnectivity است که اطلاعاتی در مورد وضعیت آنلاین و موقعیت یک صفت (مسیریابی محلی یا راه دور) دارد.

نوع اولیه یک دستگاه را دریافت کنید

برخی از دستگاه‌ها ممکن است چندین نوع دستگاه را از طریق APIهای Home ارائه دهند. برای اطمینان از اینکه گزینه‌های مناسب در یک برنامه (مانند کنترل دستگاه و اتوماسیون‌های پیشنهادی) برای دستگاه‌هایشان به کاربران ارائه می‌شود، بررسی اینکه آیا نوع دستگاه نوع اصلی دستگاه است، مفید است.

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.")
  }
}

بررسی کنید که آیا یک ویژگی آنلاین است یا خیر

ویژگی connectivityState را بخوانید تا اتصال یک ویژگی را بررسی کنید:

let levelControlConnectivity =
  levelControlTrait.metadata.sourceConnectivity
  .connectivityState

اگر دستگاه اتصال اینترنت نداشته باشد، برخی از ویژگی‌ها، معمولاً ویژگی‌های smart home Google، ممکن است آفلاین نشان داده شوند. این به این دلیل است که این ویژگی‌ها مبتنی بر ابر هستند و مسیریابی محلی ندارند.

اتصال دستگاه را بررسی کنید

اتصال برای یک دستگاه در واقع در سطح نوع دستگاه بررسی می شود زیرا برخی از دستگاه ها از چندین نوع دستگاه پشتیبانی می کنند. حالت بازگشتی ترکیبی از حالت های اتصال برای همه صفات موجود در آن دستگاه است.

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

در صورت عدم اتصال به اینترنت، ممکن است در مورد انواع دستگاه های مختلط، وضعیت partiallyOnline مشاهده شود. ممکن است به دلیل مسیریابی محلی، ویژگی‌های استاندارد Matter همچنان آنلاین باشند، اما ویژگی‌های مبتنی بر ابر آفلاین خواهند بود.

مسیریابی شبکه یک صفت را بررسی کنید

محل برای یک صفت نیز در APIهای Home موجود است. dataSourceLocality نشان می دهد که آیا این ویژگی از راه دور (از طریق ابر)، به صورت محلی (از طریق یک هاب محلی)، یا همتا به همتا (مستقیم از دستگاهی به دستگاه دیگر، بدون هاب) هدایت می شود.

برای مثال، زمانی که یک برنامه در حال بوت شدن است و هنوز به هاب یا سروری برای اتصال دستگاه نرسیده است، مقدار محلی نامشخص unspecified ممکن است. این دستگاه‌ها قابل دسترسی نیستند و درخواست‌های تعامل از سوی فرمان‌ها یا رویدادها را انجام نمی‌دهند. این به مشتری بستگی دارد که نحوه کار با چنین دستگاه هایی را تعیین کند.

let levelControlLocality =
  levelControlTrait.metadata.sourceConnectivity
  .dataSourceLocality

مسیریابی شبکه را برای یک دستگاه بررسی کنید

مانند اتصال، محل در سطح نوع دستگاه بررسی می شود. حالت برگردانده شده ترکیبی از محلی برای همه صفات در آن دستگاه است.

let lightLocality =
  dimmableLightDeviceType.metadata.sourceConnectivity.dataSourceLocality

ممکن است در سناریوی مشابهی مانند اتصال partiallyOnline حالت mixed مشاهده شود: برخی از ویژگی‌ها مبتنی بر ابر هستند در حالی که برخی دیگر محلی هستند.

نام یک دستگاه را تغییر دهید

برای تغییر نام یک دستگاه، متد setName(_:) را فراخوانی کنید:

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

هنگام تغییر نام یک دستگاه، ساختار اصلی HomeDevice ثابت می ماند و تغییر در شی HomeDevice به روز شده بازگردانده شده منعکس می شود.

اگر بیش از 60 نقطه کد یونیکد (نویسه) حد مجاز باشد، نام ها کوتاه می شوند و هیچ خطایی ایجاد نمی شود. توسعه‌دهندگان مسئول رسیدگی به نام‌های طولانی هستند و به عنوان مثال، می‌توانند تصمیم بگیرند که آیا می‌خواهند به کاربران اطلاع دهند که نام‌های کوتاه می‌شوند یا خیر.

لیست API

هنگامی که یک نمونه از Home ایجاد می شود، API های دستگاه زیر از طریق آن قابل دسترسی هستند:

هنگامی که یک HomeDevice دارید، API های زیر از طریق آن قابل دسترسی هستند: