Panduan perangkat bel pintu untuk iOS

Jenis perangkat Bel Pintu diimplementasikan menggunakan dua trait: PushAvStreamTransportTrait, yang menangani transportasi streaming audio dan video menggunakan protokol berbasis push, dan WebRtcLiveViewTrait, yang memberikan kemampuan untuk mengontrol live stream dan talkback.

Selalu periksa dukungan atribut dan perintah untuk perangkat sebelum menggunakan fitur atau mencoba memperbarui atribut. Lihat Mengontrol perangkat di iOS untuk mengetahui informasi selengkapnya.

Jenis Perangkat Home API Sifat Aplikasi Contoh Swift Kasus Penggunaan

Bel pintu

GoogleDoorbellDeviceType

home.matter.6006.types.0113

Perangkat yang diaktifkan oleh tombol di luar pintu yang menghasilkan sinyal yang dapat didengar dan/atau dilihat, yang digunakan untuk meminta perhatian orang yang berada di sisi lain pintu. Bel pintu mungkin memiliki fitur livestream yang dapat diakses, talkback dua arah, atau peristiwa deteksi.

Ciri Wajib
     google PushAvStreamTransportTrait
     google WebRtcLiveViewTrait

Bel pintu

Memulai livestream

Untuk memulai livestream, kirim string Session Description Protocol (SDP) ke metode startLiveView(offerSdp:) trait WebRtcLiveViewTrait, yang menampilkan tiga nilai:

  • SDP untuk sesi.
  • Durasi sesi dalam detik.
  • ID sesi, yang dapat digunakan untuk memperpanjang atau menghentikan sesi.
public func sendOffer(offerSdp: String) async throws
-> (answerSdp: String, mediaSessionId: String, liveViewDuration: TimeInterval)
{
  do {
    Logger.info("Sending StartLiveView command...")
    let response = try await liveViewTrait.startLiveView(
      offerSdp: offerSdp
    )
    Logger.info("Received StartLiveView response: \(response)")
    return (
      answerSdp: response.answerSdp,
      mediaSessionId: response.mediaSessionId,
      liveViewDuration: TimeInterval(response.liveSessionDurationSeconds)
    )
  } catch {
    Logger.error("Failed to send StartLiveView command: \(error)")
    throw error
  }
}

Memperpanjang livestream

Livestream memiliki durasi preset yang akan berakhir setelah durasi tersebut. Untuk memperpanjang durasi streaming aktif, kirim permintaan perpanjangan menggunakan metode extendLiveView(mediaSessionId:optionalArgsProvider:):

public func extendLiveView(mediaSessionId: String) async throws {
  do {
    Logger.info("Extending live view...")
    let extendedDuration = try await liveViewTrait.extendLiveView(mediaSessionId: mediaSessionId)
    Logger.info("Extended live view for \(extendedDuration.liveSessionDurationSeconds) seconds.")
  } catch {
    Logger.error("Failed to extend live view: \(error)")
    throw error
  }
}

Memulai dan menghentikan TalkBack

Untuk memulai talkback, panggil metode startTalkback(mediaSessionId:optionalArgsProvider:) dari WebRtcLiveViewTrait trait. Untuk berhenti, gunakan stopTalkback(mediaSessionId:).

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

Mengaktifkan dan menonaktifkan kemampuan perekaman

Untuk mengaktifkan kemampuan perekaman kamera, teruskan TransportStatusEnum.Active ke metode setTransportStatus(transportStatus:optionalArgsProvider:) trait PushAvStreamTransportTrait. Untuk menonaktifkan kemampuan merekam, teruskan TransportStatusEnum.Inactive. Dalam contoh berikut, kita menggabungkan panggilan ini dalam satu panggilan yang menggunakan Boolean untuk mengaktifkan/menonaktifkan kemampuan perekaman:

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

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

Mengaktifkan atau menonaktifkan kemampuan perekaman kamera sama dengan mengaktifkan atau menonaktifkan video kamera. Jika video kamera aktif, kamera akan merekam (untuk tujuan peristiwa dan klip terkait).

Jika kemampuan perekaman dinonaktifkan (video kamera nonaktif):

  • Kamera masih dapat ditampilkan sebagai online sesuai dengan connectivityState jenis perangkat.
  • Livestream tidak dapat diakses, dan kamera tidak mendeteksi peristiwa cloud apa pun.

Periksa apakah kemampuan perekaman diaktifkan

Untuk menentukan apakah kemampuan perekaman kamera diaktifkan, periksa apakah ada koneksi yang aktif. Contoh berikut menentukan dua fungsi untuk melakukannya:

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

Setelan audio

Berbagai setelan audio kamera dapat dikontrol melalui Home API.

Mengaktifkan atau menonaktifkan mikrofon

Untuk mengaktifkan atau menonaktifkan mikrofon perangkat, perbarui atribut microphoneMuted dari trait CameraAvStreamManagementTrait menggunakan fungsi setMicrophoneMuted bawaan:

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

Mengaktifkan atau menonaktifkan rekaman audio

Untuk mengaktifkan atau menonaktifkan perekaman audio untuk perangkat, perbarui atribut recordingMicrophoneMuted dari trait CameraAvStreamManagementTrait menggunakan fungsi setRecordingMicrophoneMuted bawaan:

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

Menyesuaikan volume speaker

Untuk menyesuaikan volume speaker perangkat, perbarui atribut speakerVolumeLevel dari trait CameraAvStreamManagementTrait menggunakan fungsi setSpeakerVolumeLevel bawaan:

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

Setelan lainnya

Berbagai setelan kamera lainnya dapat dikontrol melalui API Home.

Mengaktifkan atau menonaktifkan penglihatan malam

Untuk mengaktifkan atau menonaktifkan penglihatan malam untuk kamera, gunakan TriStateAutoEnum untuk memperbarui atribut nightVision dari sifat CameraAvStreamManagementTrait menggunakan fungsi setNightVision bawaan:

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

Mengubah kecerahan LED status

Untuk mengubah kecerahan LED status, gunakan ThreeLevelAutoEnum untuk memperbarui atribut statusLightBrightness dari trait CameraAvStreamManagementTrait menggunakan fungsi setStatusLightBrightness bawaan:

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

Mengubah area pandang kamera

Viewport kamera sama dengan fitur Zoom dan Pangkas yang dijelaskan dalam artikel dukungan Memperbesar dan mengoptimalkan video kamera Nest.

Area tampilan ditentukan dalam ViewportStruct yang berisi empat nilai, yang digunakan sebagai koordinat area tampilan. Koordinat didefinisikan sebagai:

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

Penentuan nilai untuk ViewportStruct bergantung pada UI aplikasi dan implementasi kamera. Pada tingkat yang sangat mendasar, untuk menyetel area tampilan video kamera, perbarui atribut viewport dari sifat CameraAvStreamManagementTrait dengan ViewportStruct, menggunakan fungsi setViewport bawaan.

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

}

Membuat TransportOptionsStruct

Beberapa setelan memerlukan modifikasi pada properti di TransportOptionsStruct, yang kemudian diteruskan ke opsi transportasi koneksi streaming. Untuk Swift, struct ini harus dibuat sebelum memperbarui properti apa pun.

Gunakan fungsi bantuan ini untuk membuat struct yang akan digunakan dengan perubahan setelan berikut:

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
}

Menyesuaikan sensitivitas aktivasi perangkat

Sensitivitas aktif perangkat digunakan untuk menghemat baterai dengan mengurangi rentang saat perangkat dapat mendeteksi aktivitas dan meningkatkan waktu untuk aktif setelah mendeteksi aktivitas tersebut.

Di Home API, ini dapat disetel menggunakan properti motionSensitivity dari triggerOptions di transportOptions perangkat. Opsi ini ditentukan dalam trait PushAvStreamTransportTrait untuk setiap perangkat.

Sensitivitas aktivasi hanya dapat disetel ke nilai berikut:

  • 1 = Rendah
  • 5 = Sedang
  • 10 = Tinggi

Proses pembaruan adalah dengan menemukan konfigurasi transportasi untuk aliran rekaman aktif menggunakan perintah findTransport, lalu mengubah konfigurasi dengan nilai sensitivitas baru menggunakan perintah modifyPushTransport.

Perintah modifyPushTransport memerlukan TransportOptionsStruct lengkap untuk diteruskan, jadi Anda harus menyalin nilai yang ada dari konfigurasi saat ini terlebih dahulu. Lihat Membuat TransportOptionsStruct untuk fungsi bantuan guna melakukannya.

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

Menyesuaikan durasi peristiwa maksimum

Durasi peristiwa maksimum adalah durasi waktu kamera akan merekam klip untuk suatu peristiwa. Melalui Home API, hal ini dapat dikonfigurasi, per perangkat, dengan panjang yang sama seperti melalui Google Home app (GHA), dalam interval detik:

  • 10 detik
  • 15 detik
  • 30 detik
  • 60 detik (1 menit)
  • 120 detik (2 menit)
  • 180 detik (3 menit)

Di Home API, ini dapat disetel menggunakan properti motionTimeControl dari triggerOptions di transportOptions perangkat. Opsi ini ditentukan dalam trait PushAvStreamTransportTrait untuk setiap perangkat.

Proses pembaruan adalah menemukan konfigurasi transportasi untuk aliran rekaman aktif menggunakan perintah findTransport, lalu mengubah konfigurasi dengan nilai panjang peristiwa baru menggunakan perintah modifyPushTransport.

Perintah modifyPushTransport memerlukan TransportOptionsStruct lengkap untuk diteruskan, jadi Anda harus menyalin nilai yang ada dari konfigurasi saat ini terlebih dahulu. Lihat Membuat TransportOptionsStruct untuk fungsi bantuan guna melakukannya.

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

Setelan bel

Berbagai setelan bunyi bel pintu dapat dikontrol melalui Home API.

Mengubah suara bel

Untuk mengubah suara bel pintu, pertama-tama dapatkan daftar suara bel yang diinstal di perangkat, menggunakan atribut installedChimeSounds dari trait ChimeTrait:

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

Kemudian, update atribut selectedChime dari trait ChimeTrait menggunakan fungsi setSelectedChime bawaan:

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

Menggunakan bel eksternal

Bel pintu dapat dikonfigurasi untuk menggunakan bel eksternal, seperti bel mekanis yang dipasang di dalam rumah. Setelan ini harus dikonfigurasi selama pemasangan bel pintu untuk menghindari potensi kerusakan pada bel eksternal.

Untuk menunjukkan jenis bel eksternal yang terpasang, gunakan ExternalChimeType untuk memperbarui atribut externalChime dari trait ChimeTrait menggunakan fungsi setExternalChime bawaan:

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

Mengubah durasi bel eksternal

Durasi dering bel eksternal, dalam detik, dapat dikonfigurasi melalui Home API. Jika bel eksternal mendukung durasi bel, pengguna mungkin ingin mengonfigurasi durasi ini.

Nilai yang ditetapkan di sini bergantung pada spesifikasi bel eksternal itu sendiri, dan durasi bel yang direkomendasikan.

Untuk mengubah durasi bunyi bel eksternal, perbarui atribut externalChimeDurationSeconds dari trait ChimeTrait menggunakan fungsi setExternalChimeDurationSeconds bawaan:

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