iOS 裝置適用的 Chime 裝置指南

基本 Chime 裝置類型可使用標準 Matter 型 Matter.ChimeTrait 或 Google 自訂的特徵版本 Google.ChimeTrait 實作，除了 Matter 標準中指定的功能外，還支援外部鈴聲。鈴聲裝置也可以實作 Matter.IdentifyTrait，方便使用者透過視覺或聲音辨識鈴聲裝置。

使用任何功能或嘗試更新屬性之前，請務必先檢查裝置是否支援屬性和指令。詳情請參閱「透過iOS控制裝置」。

Home API 裝置類型 特徵 Swift 範例應用程式 用途

電鈴

ChimeDeviceType

home.matter.0000.types.0146

這類裝置可播放一系列預先安裝的音效，通常會搭配門鈴、語音門鈴或視訊門鈴使用。

 必要特徵
     matter ChimeTrait

選用特徵
     matter IdentifyTrait
 門鈴

取得裝置的基本資訊

   在 iOS 範例應用程式中導入   

BasicInformation 特徵包括裝置的供應商名稱、供應商 ID、產品 ID、產品名稱 (包括型號資訊) 和軟體版本等資訊：

let vendorName = basicInfoTrait.attributes.vendorName!
let vendorID = basicInfoTrait.attributes.vendorID!
let productID = basicInfoTrait.attributes.productID!
let productName = basicInfoTrait.attributes.productName!
let softwareVersion = basicInfoTrait.attributes.softwareVersion!

支援多部分

電鈴可以由多種裝置類型組成，包括電鈴和選用的喇叭。此外，部分鈴聲會加入 Thread Border Router (TBR)，為確保支援範圍最廣，控制電鈴的 Home API 應用程式應編寫為可配合多部分電鈴裝置。詳情請參閱「多部分裝置」。

應用程式中應以單一動態磚代表每個多部分鈴聲裝置。Chime 裝置應為主要裝置，而子音箱應為 Chime 底下的零件。

電鈴裝置的主要設定應會顯示喇叭音量。

OnOff 對應

如果鈴聲同時具有 Chime 和 Speaker 裝置類型，控制應用程式中的 OnOff 按鈕應對應至 Chime 的 Enabled 屬性。

根據Matter裝置媒體庫規格，將鈴聲特徵的 Enabled 屬性設為 False，除了停用鈴聲外，還可能像全域靜音切換開關一樣，抑制所有可聽見和可見的指標。

自動化支援

如前所述，由於 ChimeDeviceType 可能有多個零件，因此建議開發人員將所有鈴聲視為多零件裝置，使用鈴聲的自動化作業也是如此。

鈴聲可用於自動化啟動條件和動作。

自動化動作中使用的父項 Chime 裝置下的任何元件裝置，都必須使用 AutomationPartPath 參照。

下列自動化動作示範如何建立自動化動作，其中包含實作 Chime 特徵和 Speaker 的多部分鈴聲。前門開啟時觸發自動化動作：

import GoogleHomeSDK
import GoogleHomeTypes

typealias ChimeTrait = Matter.ChimeTrait
typealias OpenCloseTrait = Google.OpenCloseTrait

// Fetch devices using the multipart device model.
let multipartDevices = try await home.devices(enableMultipartDevices: true).list()

guard let chimeParentDevice = multipartDevices.first(where: {
  $0.types.contains(ChimeDeviceType.self)
}) else { return }

guard let doorDevice = multipartDevices.first(where: {
  $0.types.contains(GoogleDoorDeviceType.self)
}) else { return }

// Extract the AutomationPartPath for the specific Chime part
guard let chimeType = await chimeParentDevice.types.get(ChimeDeviceType.self),
  let chimePartPath = chimeParentDevice.automationPart(chimeType) else {
  return
}

let starterNode = starter(doorDevice, GoogleDoorDeviceType.self, OpenCloseTrait.self)

let doorOpenClose = stateReader(doorDevice, GoogleDoorDeviceType.self, OpenCloseTrait.self)

// Build the automation
let chimeAutomation = automation(
  name: "Multipart Chime Demo",
  description: "Activate the chime when the door is opened"
) {
starterNode
condition {
  starterNode.openPercent.unwrapOptional().greaterThan(0)
}
  // Action: Play a chime sound
  action(chimePartPath) {
    ChimeTrait.playChimeSound()
  }
}

如要進一步瞭解使用多部裝置的自動化動作，請參閱「多部裝置自動化動作」。

檢查裝置的連線狀態

裝置的連線狀態實際上是在裝置類型層級檢查，因為部分裝置支援多種裝置類型。傳回的狀態是該裝置上所有特徵的連線狀態組合。

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

如果沒有網際網路連線，混合裝置類型可能會處於 partiallyOnline 狀態。Matter標準特徵可能仍會透過本機路徑保持連線，但雲端特徵會離線。

取得裝置的 IP 位址

如要找出裝置的 IP 位址，請使用 GeneralDiagnosticsTrait 的 networkInterfaces 屬性。位址會以 Data 物件的形式傳回，您可以使用 Network 架構將位址格式設為標準 IPv4 或 IPv6 字串：

func getIpAddresses(trait: Matter.GeneralDiagnosticsTrait) -> [String] {
  let interfaces = trait.attributes.networkInterfaces ?? []
  var ipAddresses: [String] = []

  for interface in interfaces {
    for data in interface.iPv4Addresses {
      if let ipv4 = IPv4Address(data) {
        ipAddresses.append(String(describing: ipv4))
      }
    }
    for data in interface.iPv6Addresses {
      if let ipv6 = IPv6Address(data) {
        ipAddresses.append(String(describing: ipv6))
      }
    }
  }

  return ipAddresses
}