Truy cập vào thiết bị và siêu dữ liệu thiết bị cho iOS

bookmark_border Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Bạn có thể truy cập vào API thiết bị thông qua API Home cho iOS. Nhập các gói sau vào ứng dụng:

import GoogleHomeSDK
import GoogleHomeTypes

Để biết thêm thông tin, hãy xem bài viết Mô hình dữ liệu trên iOS.

Xử lý lỗi

Một số phương thức trong API Home sẽ gửi một HomeError, vì vậy, bạn nên sử dụng khối do-catch để phát hiện HomeError trên các lệnh gọi đó.

Khi xử lý HomeError, hãy kiểm tra các trường code và message để tìm hiểu xem đã xảy ra lỗi gì.

Mọi lỗi không được xử lý sẽ khiến ứng dụng của bạn gặp sự cố.

Để biết thêm thông tin, hãy xem phần Xử lý lỗi.

Hãy xem phần Gửi lệnh đến một thiết bị để biết ví dụ.

Lệnh gọi mẫu

Lấy danh sách thiết bị

Với tham chiếu đến đối tượng Home, hãy gọi devices() để lấy Query của các thiết bị hỗ trợ tiếp cận. Gọi phương thức batched() của Query. Phương thức này sẽ phát ra một Tập hợp phản ánh trạng thái hiện tại của Trang chủ với mọi thay đổi về siêu dữ liệu thiết bị. Hoặc gọi Query.list() để xem nhanh các thiết bị có sẵn. Đây là một phương thức thuận tiện để đăng ký theo dõi luồng batched() và trả về giá trị đầu tiên được phát. Query.stream() tạo ra một luồng phát ra các giá trị mới khi siêu dữ liệu của thiết bị thay đổi, chẳng hạn như tên, phòng hoặc cấu trúc. Trong nội bộ, phương thức này sử dụng batched() và chỉ phát ra các thuộc tính đã thay đổi.

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

Từ đó, bạn có thể truy cập vào trạng thái của từng thiết bị và gửi các lệnh được hỗ trợ đến thiết bị.

Lấy các loại thiết bị

Để lấy các loại thiết bị được liên kết với một thiết bị, hãy đọc thuộc tính types của thiết bị. Thuộc tính này sẽ trả về một DeviceTypeController.

Gọi DeviceTypeController.subscribe(_:) để đăng ký nhận thông tin cập nhật cho một loại thiết bị cụ thể:

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

Nếu không hỗ trợ loại thiết bị đã chỉ định, thiết bị sẽ trả về một Empty Publisher hoàn tất ngay lập tức.

Nếu thiết bị hỗ trợ một loại thiết bị cụ thể, bạn có thể lấy một handle cho loại thiết bị đó bằng cách gọi get():

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

Nếu thiết bị không hỗ trợ loại đã chỉ định, thì thiết bị sẽ trả về nil.

Gọi DeviceTypeController.subscribeAll() để lấy Publisher của DeviceTypeCollection. Lớp này cho phép bạn kiểm tra xem thiết bị có một loại thiết bị cụ thể hay không:

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

Nhận đặc điểm loại thiết bị

Loại thiết bị là điểm truy cập để đọc các đặc điểm, vì các loại thiết bị này phân ly thiết bị thành các phần chức năng (chẳng hạn như các điểm cuối trong Matter).

Các thuộc tính này cũng tính đến các xung đột đặc điểm trong trường hợp một thiết bị có hai loại thiết bị, cả hai đều có thể có cùng một đặc điểm. Ví dụ: nếu một thiết bị vừa là Loa vừa là Đèn có thể điều chỉnh độ sáng, thì thiết bị đó sẽ có hai đặc điểm Bật/Tắt và hai đặc điểm Điều khiển mức.

Một loại xung đột đặc điểm khác có thể xảy ra khi một thiết bị có hai đặc điểm có cùng tên. Ví dụ: onOff có thể tham chiếu đến một thực thể của thuộc tính OnOff tiêu chuẩn hoặc có thể tham chiếu đến một thực thể của thuộc tính OnOff do nhà sản xuất xác định. Để loại bỏ mọi sự mơ hồ tiềm ẩn về trường hợp sử dụng của một đặc điểm, hãy tham chiếu một đặc điểm thông qua một trong hai bộ sưu tập đặc điểm trên mỗi loại thiết bị.

Đối với các đặc điểm chuẩn, tức là những đặc điểm tương tự như các cụm chuẩn Matter, hãy sử dụng matterTraits. Ví dụ: để lấy một đặc điểm cụ thể cho loại thiết bị Đèn có thể điều chỉnh độ sáng:

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

Đối với các đặc điểm của Google, hãy sử dụng googleTraits:

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

Để truy cập vào một đặc điểm dành riêng cho nhà sản xuất, hãy tham chiếu đặc điểm đó thông qua thuộc tính traits, nhưng đặt tên gói của nhà sản xuất ở phía trước:

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
}

Đọc trạng thái thiết bị

Hãy xem ví dụ sau về cách kiểm tra thuộc tính OnOff từ thuộc tính Bật/Tắt của thiết bị:

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
}

Lấy danh sách thiết bị có một đặc điểm cụ thể

Để nhận danh sách thiết bị có một đặc điểm cụ thể, bạn cần lặp lại các thiết bị, loại thiết bị của từng thiết bị và đặc điểm của từng loại thiết bị. Ví dụ: để nhận danh sách các thiết bị trong nhà đều có thuộc tính Bật/Tắt:

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

Hãy xem phần Chỉ mục đặc điểm trên iOS để biết danh sách đầy đủ các đặc điểm có trong API Home.

Lấy danh sách các thiết bị có loại thiết bị tương tự

Cách xem danh sách các thiết bị đại diện cho tất cả đèn trong nhà:

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

Có nhiều loại thiết bị trong API Home có thể đại diện cho một loại thiết bị cốt lõi. Ví dụ: không có loại thiết bị "Đèn". Thay vào đó, có bốn loại thiết bị khác nhau có thể biểu thị một ánh sáng, như trong ví dụ trước. Do đó, để có được thông tin toàn diện về loại thiết bị cấp cao hơn trong nhà, bạn phải thêm nhiều loại thiết bị.

Hãy xem phần Các loại thiết bị được hỗ trợ trên iOS để biết danh sách đầy đủ các loại thiết bị và các đặc điểm của chúng có trong API Home.

Lấy Tên nhà cung cấp, Mã nhà cung cấp hoặc Mã sản phẩm của một thiết bị

Thuộc tính BasicInformationTrait bao gồm các thông tin như Mã nhà cung cấp, Mã sản phẩm, Tên sản phẩm và Số sê-ri của thiết bị:

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

Nhận dạng thiết bị từ đám mây đến đám mây cho nhà sản xuất thiết bị

Nếu là nhà sản xuất thiết bị và xây dựng thiết bị Cloud-to-cloud, để xác định thiết bị Cloud-to-cloud thông qua đặc điểm BasicInformation, bạn có thể đưa các trường chuỗi này vào phản hồi SYNC:

• Mã nhà cung cấp do Connectivity Standards Alliance (CSA) phát hành: "matterOriginalVendorId": "0xfff1",

• Mã nhận dạng sản phẩm giúp nhận dạng duy nhất một sản phẩm của nhà cung cấp: "matterOriginalProductId": "0x1234",

• Giá trị nhận dạng duy nhất của thiết bị, được tạo theo cách dành riêng cho nhà sản xuất: "matterUniqueId": "matter-device-id",

Khi nhập các trường chuỗi này, hãy sử dụng mã nhận dạng Nhà cung cấp và mã nhận dạng sản phẩm Matter nếu bạn có. Nếu không phải là thành viên CSA và chưa được chỉ định các mã nhận dạng này, bạn có thể để trống các trường matterOriginalVendorId và matterOriginalProductId rồi cung cấp matterUniqueId làm giá trị nhận dạng.

Phản hồi SYNC mẫu cho thấy cách sử dụng các trường này:

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

Để biết thêm thông tin, hãy xem tài liệu về Cloud-to-cloud SYNC.

Siêu dữ liệu về thiết bị và đặc điểm

Các thiết bị và đặc điểm trong API Home có siêu dữ liệu liên kết với chúng, giúp quản lý trải nghiệm người dùng trong ứng dụng.

Mỗi đặc điểm trong API Home chứa một thuộc tính sourceConnectivity. Thuộc tính này có thông tin về trạng thái trực tuyến và vị trí của một đặc điểm (định tuyến cục bộ hoặc từ xa).

Lấy loại chính của thiết bị

Một số thiết bị có thể hiển thị nhiều loại thiết bị thông qua API Home. Để đảm bảo người dùng được cung cấp các tuỳ chọn phù hợp trong ứng dụng (chẳng hạn như tính năng điều khiển thiết bị và tính năng tự động hoá được đề xuất) cho thiết bị của họ, bạn nên kiểm tra xem loại thiết bị có phải là loại thiết bị chính hay không.

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

Kiểm tra xem một đặc điểm có đang trực tuyến hay không

Đọc thuộc tính connectivityState để kiểm tra khả năng kết nối của một đặc điểm:

let levelControlConnectivity =
  levelControlTrait.metadata.sourceConnectivity
  .connectivityState

Một số đặc điểm, thường là các đặc điểm smart home của Google, có thể hiển thị ngoại tuyến nếu thiết bị không có kết nối Internet. Nguyên nhân là do các đặc điểm này dựa trên đám mây và không có định tuyến cục bộ.

Kiểm tra khả năng kết nối của thiết bị

Khả năng kết nối của một thiết bị thực sự được kiểm tra ở cấp loại thiết bị vì một số thiết bị hỗ trợ nhiều loại thiết bị. Trạng thái được trả về là kết hợp của các trạng thái kết nối cho tất cả các đặc điểm trên thiết bị đó.

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

Bạn có thể quan sát trạng thái partiallyOnline trong trường hợp các loại thiết bị kết hợp nhau khi không có kết nối Internet. Các đặc điểm tiêu chuẩn Matter vẫn có thể trực tuyến do định tuyến cục bộ, nhưng các đặc điểm dựa trên đám mây sẽ ở chế độ ngoại tuyến.

Kiểm tra định tuyến mạng của một đặc điểm

Vị trí của một đặc điểm cũng có trong API Home. dataSourceLocality cho biết liệu đặc điểm có được định tuyến từ xa (thông qua đám mây), cục bộ (thông qua một trung tâm cục bộ) hay ngang hàng (trực tiếp từ thiết bị đến thiết bị, không có trung tâm).

Giá trị vị trí không xác định unspecified có thể xảy ra, ví dụ: trong khi một ứng dụng đang khởi động và chưa kết nối với một trung tâm hoặc máy chủ để kết nối thiết bị. Bạn không thể truy cập vào các thiết bị này và các yêu cầu tương tác từ các lệnh hoặc sự kiện sẽ không thành công. Việc xác định cách xử lý các thiết bị như vậy là tuỳ thuộc vào ứng dụng.

let levelControlLocality =
  levelControlTrait.metadata.sourceConnectivity
  .dataSourceLocality

Kiểm tra định tuyến mạng cho một thiết bị

Giống như khả năng kết nối, vị trí được kiểm tra ở cấp loại thiết bị. Trạng thái được trả về là sự kết hợp của vị trí cho tất cả các đặc điểm trên thiết bị đó.

let lightLocality =
  dimmableLightDeviceType.metadata.sourceConnectivity.dataSourceLocality

Bạn có thể quan sát trạng thái mixed trong một trường hợp tương tự như trạng thái kết nối partiallyOnline: một số đặc điểm dựa trên đám mây còn một số khác thì dựa trên cục bộ.

Danh sách API

Sau khi tạo một thực thể của Home, bạn có thể truy cập vào các API Thiết bị sau thông qua thực thể đó:

Sau khi bạn có HomeDevice, bạn có thể truy cập vào các API sau thông qua API đó: