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

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

import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.Id

Để sử dụng các loại hoặc đặc điểm thiết bị cụ thể với API Thiết bị, bạn phải nhập từng loại hoặc đặc điểm đó.

Ví dụ: để sử dụng đặc điểm Bật/Tắt Matter và loại thiết bị Đơn vị cắm Bật/Tắt, hãy nhập các gói sau vào ứng dụng:

import com.google.home.matter.standard.OnOff
import com.google.home.matter.standard.OnOffPluginUnitDevice

Để biết thêm thông tin, hãy xem phần Mô hình dữ liệu.

Xử lý lỗi

Bất kỳ phương thức nào trong API Home đều có thể gửi một HomeException, vì vậy, bạn nên sử dụng khối try-catch để phát hiện HomeException trên tất cả các lệnh gọi.

Khi xử lý HomeException, 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 ngoại lệ chưa đượ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 thiết bị để biết ví dụ.

Lệnh gọi mẫu

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

Khi có cấu trúc, lệnh gọi devices() sẽ trả về một Flow của các thiết bị mà bạn có thể truy cập từ cấu trúc đó:

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

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ị.

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

Hãy xem ví dụ 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ị. Khi sử dụng mô hình dữ liệu đặc điểm API Home, trong đó đặc điểm này được xác định là OnOff, bạn có thể truy xuất dữ liệu đặc điểm thông qua lớp standardTraits của loại thiết bị:

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

Hãy xem distinctUntilChanged để tìm hiểu thêm về hàm flow trong Kotlin.

Huỷ hiệu lực trạng thái trong gói thuê bao đặc điểm

Giao diện TraitStateInvalidation cung cấp khả năng vô hiệu hoá trạng thái được truy xuất thông qua các gói thuê bao đến thiết bị mục tiêu trong trường hợp trạng thái không được báo cáo chính xác. Ví dụ về trường hợp trạng thái có thể không được báo cáo chính xác bao gồm việc sử dụng các thuộc tính trong đặc điểm Matter có chất lượng "C" hoặc do việc triển khai thiết bị gây ra vấn đề ngoài dự kiến.

API này thực hiện lệnh đọc bắt buộc trạng thái đặc điểm hiện tại và trả về kết quả thông qua các luồng đặc điểm hiện có.

Lấy đặc điểm, sau đó chạy forceRead trên đặc điểm đó:

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

Lấy danh sách các đặc điểm của loại thiết bị

Bạn nên sử dụng loại thiết bị làm điểm truy cập để đọc các đặc điểm, vì các loại thiết bị này phân tích 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 lớp 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.

Cách xem danh sách các đặc điểm có sẵn cho loại thiết bị Đèn có thể điều chỉnh độ sáng:

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

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ề đặc điểm nào được dự định, một thực thể Trait được tham chiếu thông qua một thiết bị phải đứng trước một không gian tên đủ điều kiện. Đố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 standardTraits. Đối với các đặc điểm của Google, hãy sử dụng googleTraits:

// Accessing standard traits on the type.
val onOffTrait: OnOff? = dimmableLightDevice.standardTraits.onOff
val levelControlTrait: LevelControl? = dimmableLightDevice.standardTraits.levelControl

Để 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 trực tiếp đặc điểm đó:

// Accessing a custom trait on the type.
val customTrait = dimmableLightDevice.trait(MyCustomTrait)

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

Bạn có thể sử dụng hàm filter trong Kotlin để tinh chỉnh thêm các lệnh gọi API. Ví dụ: để lấy danh sách các thiết bị trong nhà đều có thuộc tính Bật/Tắt:

// Get all devices that support OnOff
val onOffDevices: Flow<List<HomeDevice>> =
  home.devices().map { devices -> devices.filter { it.has(OnOff) } }

Hãy xem giao diện Trait để 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)
val lightDevices =
  home.devices().map { devices ->
    devices.filter {
      it.has(DimmableLightDevice) ||
        it.has(OnOffLightDevice) ||
        it.has(ColorTemperatureLightDevice) ||
        it.has(ExtendedColorLightDevice)
    }
  }

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 đèn, 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 một gia đình, bạn phải đưa nhiều loại thiết bị vào luồng đã lọc.

Hãy xem giao diện DeviceType để biết danh sách đầy đủ các loại thiết bị có trong API Home.

Lấy mã nhà cung cấp hoặc mã sản phẩm cho một thiết bị

Thuộc tính BasicInformation bao gồm 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ị:

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

Xác định thiết bị từ đám mây đến đám mây

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ận dạng nhà cung cấp do Liên minh Tiêu chuẩn Kết nối (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 Matter Mã nhà cung cấp và Mã sản phẩm 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 và 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 loại thiết bị chính của thiết bị.

Trước tiên, hãy lấy(các) loại thiết bị bằng cách sử dụng type(), sau đó xác định loại chính:

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

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

Sử dụng phương thức connectivityState() để kiểm tra khả năng kết nối của một đặc điểm:

val onOffConnectivity = onOffTrait?.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ị khi 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ó tính năng đị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ị đó.

val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState

Bạn có thể quan sát trạng thái PARTIALLY_ONLINE trong trường hợp thiết bị kết hợp khi không có kết nối Internet. Các đặc điểm tiêu chuẩn của Matter có thể vẫn hoạt động 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ẽ hoạt động 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 này 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 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à sẽ không thực hiện được yêu cầu tương tác từ các lệnh hoặc sự kiện. Khách hàng có thể tự quyết định cách xử lý các thiết bị như vậy.

val onOffLocality = onOffTrait?.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ị đó.

val lightLocality = dimmableLightDevice.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 PARTIALLY_ONLINE: một số đặc điểm dựa trên đám mây trong khi các đặc điểm khác là 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 có HomeDevice, bạn có thể truy cập các API sau thông qua API đó: