iOS 裝置適用的門鈴裝置指南

門鈴裝置類型是透過兩種特徵實作：PushAvStreamTransportTrait，可使用以推送為基礎的通訊協定處理音訊和影片串流傳輸；WebRtcLiveViewTrait，可控制即時串流和對講功能。

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

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

門鈴

GoogleDoorbellDeviceType

home.matter.6006.types.0113

門外的按鈕啟動裝置，會發出聲音和/或視覺信號，用於請求門另一側的人注意。門鈴可能提供無障礙直播、雙向對講或偵測事件。

 必要特徵
     google PushAvStreamTransportTrait
     google WebRtcLiveViewTrait

 門鈴

取得裝置的基本資訊

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

// [START get_device_information]
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!
let serialNumber = basicInfoTrait.attributes.serialNumber!
// [END get_device_information]

檢查裝置的連線狀態

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

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

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

開始直播

如要開始直播，請將工作階段描述通訊協定 (SDP) 字串傳送至 WebRtcLiveViewTrait 特徵的 startLiveView(offerSdp:) 方法，該方法會傳回三個值：

  • 工作階段的 SDP。
  • 工作階段時間長度 (以秒為單位)。
  • 工作階段 ID，可用於延長或終止工作階段。
public func sendOffer(offerSdp: String) async throws
-> (answerSdp: String, mediaSessionId: String, liveViewDuration: TimeInterval)
{
  do {
    // Sending StartLiveView command
    let response = try await liveViewTrait.startLiveView(
      offerSdp: offerSdp
    )
    // Received StartLiveView response
    return (
      answerSdp: response.answerSdp,
      mediaSessionId: response.mediaSessionId,
      liveViewDuration: TimeInterval(response.liveSessionDurationSeconds)
    )
  } catch {
    // Failed to send StartLiveView command
    throw error
  }
}

延長直播時間

直播有預設時長，時間一到就會過期。如要延長有效串流的時長，請使用 extendLiveView(mediaSessionId:optionalArgsProvider:) 方法發出延長要求：

public func extendLiveView(mediaSessionId: String) async throws {
  do {
    // Extending live view
    let extendedDuration = try await liveViewTrait.extendLiveView(mediaSessionId: mediaSessionId)
  } catch {
    // Failed to extend live view
    throw error
  }
}

啟動及停止 TalkBack

如要啟動 TalkBack，請呼叫 WebRtcLiveViewTrait 特徵的 startTalkback(mediaSessionId:optionalArgsProvider:) 方法。如要停止，請使用 stopTalkback(mediaSessionId:)。

public func toggleTwoWayTalk(isOn: Bool, mediaSessionId: String) async throws {
  do {
    if isOn {
      try await liveViewTrait.startTalkback(mediaSessionId: mediaSessionId)
    } else {
      try await liveViewTrait.stopTalkback(mediaSessionId: mediaSessionId)
    }
  } catch {
    throw HomeError.commandFailed("Failed to toggle twoWayTalk: \(error)")
  }
}

啟用及停用錄製功能

如要啟用攝影機的錄影功能，請將 TransportStatusEnum.Active 傳遞至 PushAvStreamTransportTrait 特徵的 setTransportStatus(transportStatus:optionalArgsProvider:) 方法。如要停用錄製功能，請傳遞 TransportStatusEnum.Inactive。 在以下範例中，我們將這些呼叫包裝在單一呼叫中，並使用 Boolean 切換錄音功能：

public func toggleIsRecording(isOn: Bool) {
  self.uiState = .loading

  guard let pushAvStreamTransportTrait else {
    // PushAvStreamTransportTrait not found.
    return
  }
  Task {
    do {
      try await pushAvStreamTransportTrait.setTransportStatus(
        transportStatus: isOn ? .active : .inactive)
      if isOn {
        do {
          self.player = try self.createWebRtcPlayer()
        } catch {
          // Failed to initialize WebRtcPlayer
          self.uiState = .disconnected
          return
        }
        await self.player?.initialize()
        self.uiState = .live
      } else {
        self.player = nil
        self.uiState = .off
      }
    } catch {
      // Failed to toggle onOff
    }
  }
}

啟用或停用攝影機的錄影功能，等同於開啟或關閉攝影機影像。攝影機影像開啟時，攝影機就會錄影 (用於事件和相關影像片段)。

錄製功能停用時 (攝影機影片關閉)：

  • 攝影機仍會顯示為connectivityState裝置類型的線上狀態。
  • 無法存取即時串流影像，攝影機也未偵測到任何雲端事件。

確認是否已啟用錄製功能

如要判斷攝影機是否已啟用錄影功能，請檢查是否有任何連線處於啟用狀態。以下範例定義了兩個函式來執行這項操作：

public func isDeviceRecording() -> Bool {
  guard let pushAvStreamTransportTrait else {
    // PushAvStreamTransportTrait not found.
    return false
  }
  guard
    let hasActiveConnection =
      pushAvStreamTransportTrait
      .attributes
      .currentConnections?
      .contains(where: { $0.transportStatus == .active })
  else {
    return false
  }
  return hasActiveConnection
}

電池設定

你可以透過 Home API 控制各種電池設定。

設定電池用量偏好設定

設定能源平衡可讓您在裝置的電池續航力和效能之間取捨。你可以建立不同的電池設定檔，例如「延長續航力」、「平衡」和「效能」，並在這些設定檔之間切換。

如要實作這項功能，請更新 EnergyPreference 特徵的 currentEnergyBalance 屬性。這個屬性接受與裝置 energyBalances 清單中定義的特定設定檔對應的整數索引 (例如 EXTENDED 的 0、BALANCED 的 1，以及 PERFORMANCE 的 2)。

currentEnergyBalance 的 null 值表示裝置使用自訂設定檔。這是唯讀狀態。

以下範例顯示 currentEnergyBalance 屬性使用的結構，接著是使用該屬性的實際程式碼片段。

// Example energyBalances list
{
  "energy_balances": [
    {
      "step": 0,
      "label": "EXTENDED"
    },
    {
      "step": 50,
      "label": "BALANCED"
    },
    {
      "step": 100,
      "label": "PERFORMANCE"
    }
  ]
}
 
private func setBatteryUsage(to option: UInt8) async throws {
  _ = try await energyPreferenceTrait.update {
    $0.setCurrentEnergyBalance(option)
  }
}

開啟自動省電模式

如要設定這項功能，請更新 EnergyPreference 特徵的 currentLowPowerModeSensitivity 屬性。這項屬性會使用索引選取感應程度，其中 0 通常代表 Disabled，而 1 代表 Enabled 或 Automatic。

private func setAutoBatterySaver(to value: Bool) async throws {
  _ = try await energyPreferenceTrait.update {
    $0.setCurrentLowPowerModeSensitivity(value ? 1 : 0)
  }
}

取得電池充電狀態

如要取得裝置目前的充電狀態 (充電中、已充飽電或未充電)，請使用 PowerSource 特徵的 batChargeState 屬性。

self.chargingState = powerSourceTrait.attributes.batChargeState

var description: String
switch self.chargingState {
case .isCharging:
  description = "Charging"
case .isAtFullCharge:
  description = "Full"
case .isNotCharging:
  description = "Not Charging"
default:
  description = "Unknown"
}

取得電池電量

如要取得目前的電池電量，請使用 PowerSource 特徵的 batChargeLevel 屬性。層級可以是 OK、Warning (低) 或 Critical。

self.batteryLevel = powerSourceTrait.attributes.batChargeLevel

var description: String
switch self.batteryLevel {
case .ok:
  description = "OK"
case .warning:
  description = "Warning"
case .critical:
  description = "Critical"
default:
  description = "Unknown"
}

取得電源

如要判斷裝置使用的電源，請使用 PowerSource 特徵的 BatPresent 和 wiredPresent 屬性。

if powerSourceTrait.attributes.wiredPresent ?? false {
  self.powerSourceType = .wired
} else if powerSourceTrait.attributes.batPresent ?? false {
  self.powerSourceType = .battery
} else {
  self.powerSourceType = nil
}

音訊設定

你可以透過 Home API 控制各種音訊設定。

開啟或關閉麥克風

如要開啟或關閉裝置麥克風，請使用內建的 setMicrophoneMuted 函式，更新 CameraAvStreamManagementTrait 特徵的 microphoneMuted 屬性：

// Turn the device's microphone on or off
func setMicrophone(on: Bool) async {
  do {
    _ = try await self.cameraAvStreamManagementTrait?.update {
      $0.setMicrophoneMuted(!on)
    }
  } catch {
    // Error
  }
}

開啟或關閉錄音功能

如要開啟或關閉裝置的錄音功能，請使用內建的 setRecordingMicrophoneMuted 函式，更新 CameraAvStreamManagementTrait 特徵的 recordingMicrophoneMuted 屬性：

// Turn audio recording on or off for the device
func setAudioRecording(on: Bool) async {
  do {
    _ = try await self.cameraAvStreamManagementTrait?.update {
      $0.setRecordingMicrophoneMuted(!on)
    }
  } catch {
    // Error
  }
}

調整音箱音量

如要調整裝置的音箱音量，請使用內建的 setSpeakerVolumeLevel 函式，更新 CameraAvStreamManagementTrait 特徵的 speakerVolumeLevel 屬性：

// Adjust the camera speaker volume
func setSpeakerVolume(to value: UInt8) async {
  do {
    _ = try await cameraAvStreamManagementTrait.update {
      $0.setSpeakerVolumeLevel(value)
    }
  } catch {
    // Error
  }
}

其他設定

您也可以透過 Home API 控制其他各種設定。

開啟或關閉夜視模式

如要開啟或關閉攝影機的夜視功能，請使用 TriStateAutoEnum 更新 CameraAvStreamManagementTrait 特徵的 nightVision 屬性，方法是使用內建的 setNightVision 函式：

// Turn night vision on or off
func setNightVision(
  to value: Google.CameraAvStreamManagementTrait.TriStateAutoEnum
) async {
  do {
    _ = try await cameraAvStreamManagementTrait.update {
      $0.setNightVision(value)
    }
  } catch {
    // Error
  }
}

變更狀態 LED 燈的亮度

如要變更狀態 LED 的亮度，請使用 ThreeLevelAutoEnum 更新 statusLightBrightness CameraAvStreamManagementTrait 特徵的屬性，方法是使用內建的 setStatusLightBrightness 函式：

// Set the LED brightness
func setStatusLightBrightness(
  to value: Google.CameraAvStreamManagementTrait.ThreeLevelAutoEnum
) async {
  do {
    _ = try await cameraAvStreamManagementTrait.update {
      $0.setStatusLightBrightness(value)
    }
  } catch {
    // Error
  }
}

變更攝影機可視區域

攝影機檢視區塊與「縮放加強 Nest 攝影機影像」支援文章中說明的「縮放及裁剪」功能相同。

視埠定義於包含四個值的 ViewportStruct 中，這些值會做為視埠的座標。座標定義如下：

(x1,y1) -- (x2,y1)
   |          |
(x1,y2) -- (x2,y2)

判斷 ViewportStruct 的值取決於應用程式的 UI 和相機實作方式。在最基本的層級，如要設定攝影機影片的檢視區塊，請使用內建的 setViewport 函式，透過 ViewportStruct 更新 CameraAvStreamManagementTrait 特徵的 viewport 屬性。

func setCrop(x1: UInt16, y1: UInt16, x2: UInt16, y2: UInt16) {

  let viewport = Google.CameraAvStreamManagementTrait.ViewportStruct(
    x1: x1,
    y1: y1,
    x2: x2,
    y2: y2
  )

  Task {
    do {
      try await cameraAvStreamManagementTrait.update {
        $0.setViewport(viewport)
      }
    } catch {
      // Error
    }
  }

}

產生 TransportOptionsStruct

部分設定需要修改 TransportOptionsStruct 中的屬性，然後傳遞至串流連線的傳輸選項。如果是 Swift，更新任何屬性前，必須先產生這個結構體。

使用這個輔助函式產生結構體，以便用於下列設定變更：

func getTransportOptions(
  transportOptions: Google.PushAvStreamTransportTrait.TransportOptionsStruct,
  wakeUpSensitivity: UInt8?,
  maxEventLength: UInt32?
) async throws
  -> Google.PushAvStreamTransportTrait.TransportOptionsStruct
{

  var newMotionTimeControl:
    Google.PushAvStreamTransportTrait.TransportMotionTriggerTimeControlStruct? = nil
  if let maxEventLength {
    guard let motionTimeControl = transportOptions.triggerOptions.motionTimeControl else {
      throw HomeError.failedPrecondition(
        // Error - cannot update max event length without motion time control
    }
    newMotionTimeControl =
      Google.PushAvStreamTransportTrait.TransportMotionTriggerTimeControlStruct(
        initialDuration: motionTimeControl.initialDuration,
        augmentationDuration: motionTimeControl.augmentationDuration,
        maxDuration: maxEventLength,
        blindDuration: motionTimeControl.blindDuration
      )
  }

  return Google.PushAvStreamTransportTrait.TransportOptionsStruct(
    streamUsage: .recording,
    videoStreamID: nil,
    audioStreamID: nil,
    tlsEndpointID: transportOptions.tlsEndpointID,
    url: transportOptions.url,
    triggerOptions: Google.PushAvStreamTransportTrait.TransportTriggerOptionsStruct(
      triggerType: .motion,
      motionZones: nil,
      motionSensitivity: wakeUpSensitivity,
      motionTimeControl: newMotionTimeControl,
      maxPreRollLen: nil
    ),
    ingestMethod: .cmafIngest,
    containerOptions: Google.PushAvStreamTransportTrait.ContainerOptionsStruct(
      containerType: .cmaf,
      cmafContainerOptions: nil
    ),
    expiryTime: nil
  )
}

private func getRecordingConnection() async throws
  -> Google.PushAvStreamTransportTrait.TransportConfigurationStruct?
{
  guard let pushAvStreamTransportTrait else {
    // Error - PushAvStreamTransport trait not available
    return nil
  }

  let connections = try await pushAvStreamTransportTrait.findTransport().transportConfigurations

  for connection in connections {
    guard let transportOptions = connection.transportOptions,
      transportOptions.streamUsage == .recording
    else {
      continue
    }

    return connection
  }

  return nil
}

調整裝置喚醒靈敏度

裝置的喚醒敏感度可縮減裝置感應活動的範圍，並延長偵測到活動後喚醒裝置的時間，藉此節省電力。

在 Home API 中，這項屬性可透過裝置 transportOptions 中的 motionSensitivity 屬性設定。triggerOptions這些選項是在每個裝置的 PushAvStreamTransportTrait 特徵中定義。

喚醒敏感度只能設為下列值：

  • 1 = 低
  • 5 = 中
  • 10 = 高

更新程序是使用 findTransport 指令找出有效錄製串流的傳輸設定，然後使用 modifyPushTransport 指令，以新的感應度值修改設定。

modifyPushTransport 指令需要傳遞完整的 TransportOptionsStruct，因此您必須先從目前的設定複製現有值。如要瞭解如何產生執行這項操作的輔助函式，請參閱「產生 TransportOptionsStruct」。

func setWakeUpSensitivity(to value: UInt8) async {
  do {
    let connection = try await getRecordingConnection()
    guard let connection,
      let transportOptions = connection.transportOptions
    else {
      // Error - Transport options not available
      return
    }

    guard transportOptions.triggerOptions.motionSensitivity != nil else {
      // Error - Motion sensitivity not available to be updated for this device
      return
    }

    try await pushAvStreamTransportTrait.modifyPushTransport(
      connectionID: connection.connectionID,
      transportOptions: self.getTransportOptions(
        transportOptions: transportOptions,
        wakeUpSensitivity: value,
        maxEventLength: nil
      )
    )

  } catch {
    // Error
  }
}

調整事件錄影時間上限

事件錄影時間上限是指攝影機錄製事件影像片段的時間長度。透過 Home API，您可以為每個裝置設定與透過 Google Home app (GHA) 相同的長度，間隔為秒：

  • 10 秒
  • 15 秒
  • 30 秒
  • 60 秒 (1 分鐘)
  • 120 秒 (2 分鐘)
  • 180 秒 (3 分鐘)

在 Home API 中，這項屬性可透過裝置 transportOptions 中的 motionTimeControl 屬性設定。triggerOptions這些選項是在每個裝置的 PushAvStreamTransportTrait 特徵中定義。

更新程序如下：使用 findTransport 指令找出有效錄製串流的傳輸設定，然後使用 modifyPushTransport 指令，以新的事件長度值修改設定。

modifyPushTransport 指令需要傳遞完整的 TransportOptionsStruct，因此您必須先從目前的設定複製現有值。如要瞭解如何產生執行這項操作的輔助函式，請參閱「產生 TransportOptionsStruct」。

func setMaxEventLength(to value: UInt32) async {
  do {
    let connection = try await getRecordingConnection()
    guard let connection,
      let transportOptions = connection.transportOptions
    else {
      // Error - Transport options not available
      return
    }

    guard transportOptions.triggerOptions.motionTimeControl != nil else {
      // Error - Motion time control not available to be updated for this device
      return
    }

    try await pushAvStreamTransportTrait.modifyPushTransport(
      connectionID: connection.connectionID,
      transportOptions: self.getTransportOptions(
        transportOptions: transportOptions,
        wakeUpSensitivity: nil,
        maxEventLength: value
      )
    )

  } catch {
    // Error
  }
}

鈴聲設定

你可以透過 Home API 控制各種門鈴鈴聲設定。

變更鈴聲音效

如要變更門鈴鈴聲，請先使用 ChimeTrait 特徵的 installedChimeSounds 屬性，取得裝置上安裝的鈴聲清單：

doorbellChimeTrait.attributes.installedChimeSounds?.compactMap { chimeSound in
  return chimeSound.chimeID, chimeSound.name
}

然後，使用內建的 setSelectedChime 函式，更新 ChimeTrait 特徵的 selectedChime 屬性：

func setDoorbellChime(chimeID: UInt8) async {
  do {
    _ = try await doorbellChimeTrait.update {
      $0.setSelectedChime(chimeID)
    }
  } catch {
    // Error
  }
}

使用外部鈴聲

你可以將門鈴設定為使用外部鈴聲，例如安裝在住家內的機械式電鈴。安裝門鈴時應設定這項功能，以免外部鈴聲可能損壞。

如要指出安裝的外部鈴聲類型，請使用 ExternalChimeType，透過內建的 setExternalChime 函式更新 ChimeTrait 特徵的 externalChime 屬性：

// Indicate the external chime is mechanical
func setExternalChime(to value: Google.ChimeTrait.ExternalChimeType) async {
  do {
    _ = try await doorbellChimeTrait.update {
      $0.setExternalChime(value)
    }
  } catch {
    // Error
  }
}

變更外部電鈴時長

你可以透過 Home API 設定外部鈴聲的響鈴時間 (以秒為單位)。如果外部鈴聲支援鈴聲持續時間，使用者可能需要設定這項功能。

此處設定的值取決於外部鈴聲本身的規格，以及建議的鈴聲長度。

如要變更外部鈴聲的持續時間，請使用內建的 setExternalChimeDurationSeconds 函式，更新 ChimeTrait 特徵的 externalChimeDurationSeconds 屬性：

// Change the external chime duration
func setExternalChimeDuration(to value: UInt16) async {
  do {
    _ = try await doorbellChimeTrait.update {
      $0.setExternalChimeDuration(value)
    }
  } catch {
    // Error
  }
}

啟用鈴聲主題

部分門鈴可能提供限時鈴聲。例如節慶專屬鈴聲。這些稱為鈴聲主題。

如要查看使用者可用的鈴聲主題，請建立時間範圍篩選器，並使用該篩選器篩選 ChimeThemes 特徵的 getAvailableThemes 指令結果。這樣會傳回可用主題清單，包括主題名稱。

以下範例說明如何篩選清單。如果目前時間介於主題的開始和結束時間 (分別為 startTimeSeconds 和 endTimeSeconds 值) 之間，系統就會將該主題視為有效。如果未設定開始時間，系統會將其視為從時間開始起就處於有效狀態。如果未設定結束時間，廣告活動會無限期持續放送。如果兩者皆未提供，主題一律會處於啟用狀態。

let chimeThemes = try await chimeThemeTrait.getAvailableThemes().themes

if !chimeThemes.isEmpty {
  var chimeThemeSettings = []
  for chimeTheme in chimeThemes {
    let currentDateTime = UInt64(Date().timeIntervalSince1970)

    // Only show chime themes that are active.
    if chimeTheme.startTimeSeconds ?? 0 <= currentDateTime
      && chimeTheme.endTimeSeconds ?? UInt64.max >= currentDateTime
    {
      self.chimeThemeSettings.append(chimeTheme.name)
    }
  }
}

取得所需主題的名稱 (例如 Christmas) 後，即可使用 ChimeThemes ChimeThemes 特徵的 setSelectedTimeboxedThemeName() 函式選取該主題。

private func setChimeTheme(to value: String) async throws {
  _ = try await chimeThemeTrait.update {
    $0.setSelectedTimeboxedThemeName(value)
  }
}```