Panduan perangkat bel pintu untuk Android

Jenis perangkat Bel Pintu diimplementasikan menggunakan dua trait: PushAvStreamTransport, yang menangani transportasi streaming audio dan video menggunakan protokol berbasis push, dan WebRtcLiveView, 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 Android untuk mengetahui informasi selengkapnya.

Memulai livestream

Untuk memulai livestream, kirim string Session Description Protocol (SDP) ke metode startLiveView() dari trait WebRtcLiveView, yang menampilkan WebRtcLiveViewTrait.StartLiveViewCommand.Response yang berisi tiga nilai:

• SDP untuk sesi.
• Durasi sesi dalam detik.
• ID sesi, yang dapat digunakan untuk memperpanjang atau menghentikan sesi.

suspend fun getWebRtcLiveViewTrait(cameraDevice: HomeDevice) {
 return cameraDevice.type(GoogleDoorbellDevice).trait(WebRtcLiveView).first {
    it?.metadata?.sourceConnectivity?.connectivityState == ConnectivityState.ONLINE
  }

}

// Start the live view
suspend fun startCameraStream(trait: WebRtcLiveView, offerSdp: String) {
  val response = trait.startLiveView(offerSdp)
  // Response contains three fields (see below)
  return response
}
  ...

// This is used to manage the WebRTC connection
val peerConnection: RTCPeerConnection = ...

   ...

val startResponse = startCameraStream(sdp)
val answerSdp = startResponse?.answerSdp
val sessionDuration = startResponse?.liveSessionDurationSeconds
val mediaSessionId = startResponse?.mediaSessionId

peerConnection.setRemoteDescription(SessionDescription.Type.ANSWER,
                                    answerSdp)

Memperpanjang livestream

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

// Assuming camera stream has just been started
suspend fun scheduleExtension(trait: WebRtcLiveView, mediaSessionId: String, liveSessionDurationSeconds: UShort ) {
  delay(liveSessionDurationSeconds - BUFFER_SECONDS * 1000)
  val response = trait.extendLiveView(mediaSessionId)
  // returns how long the session will be live for
  return response.liveSessionDurationSeconds
}

Memulai dan menghentikan TalkBack

Untuk memulai TalkBack, panggil metode startTalkback() trait WebRtcLiveView. Untuk berhenti, gunakan stopTalkback().

// Make sure camera stream is on
suspend fun setTalkback(isOn: Boolean, trait: WebRtcLiveView, mediaSessionId: String) {
  if(isOn) {
    trait.startTalkback(mediaSessionId)
  } else {
    trait.stopTalkback(mediaSessionId)
  }
}

Mengaktifkan dan menonaktifkan kemampuan perekaman

Untuk mengaktifkan kemampuan perekaman kamera, teruskan TransportStatusEnum.Active ke metode setTransportStatus() trait PushAvStreamTransport. 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:

// Start or stop recording for all connections.
suspend fun setCameraRecording(isOn: Boolean) {
  val pushAvStreamTransport = getPushAvStreamTransport
  if(isOn) {
    pushAvStreamTransport.setTransportStatus(TransportStatusEnum.Active)
  } else {
    pushAvStreamTransport.setTransportStatus(TransportStatusEnum.Inactive)
  }
}

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.

Memeriksa apakah kemampuan perekaman diaktifkan

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

// Get the on/off state
suspend fun onOffState(cameraDevice: HomeDevice, cameraDeviceType) {
  // Query the device for pushAvStreamTransport
  val pushAvTrait = getPushAvStreamTransport()
  return pushAvTrait.recordModeActive()
}

// Check if the camera's recording capability is enabled
fun PushAvStreamTransport.recordModeActive(): Boolean {
  return currentConnections?.any { it.transportStatus == TransportStatusEnum.Active } ?: false
}

Cara lain untuk memeriksa adalah menggunakan fungsi findTransport() dengan predikat:

// Fetch the current connections
suspend fun queryRecordModeState(cameraDevice: HomeDevice, cameraDeviceType) {
  val pushAvStreamTransport = getPushAvStreamTransport()
  return pushAvStreamTransport.findTransport().let {
      it.transportConfigurations.any { it.transportStatus == TransportStatusEnum.Active
    }
}

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 CameraAvStreamManagement menggunakan fungsi Kotlin setMicrophoneMuted bawaan:

// Turn the device's microphone on or off
suspend fun turnOffMicrophone(disableMicrophone: Boolean, trait: CameraAvStreamManagement) {
  trait.update { setMicrophoneMuted(disableMicrophone) }
}

Mengaktifkan atau menonaktifkan rekaman audio

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

// Turn audio recording on or off for the device
suspend fun turnOffAudioRecording(disableAudioRecording: Boolean, trait: CameraAvStreamManagement) {
  trait.update { setRecordingMicrophoneMuted(disableAudioRecording) }
}

Menyesuaikan volume speaker

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

// Adjust the camera speaker volume
suspend fun adjustSpeakerVolume(volume: Int, trait: CameraAvStreamManagement) {
  trait.update { setSpeakerVolumeLevel(volume.toUbyte()) }
}

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 trait CameraAvStreamManagement menggunakan fungsi Kotlin setNightVision bawaan:

// Turn night vision on
cameraAvStreamManagement.update {
  setNightVision(CameraAvStreamManagementTrait.TriStateAutoEnum.On)
}

// Turn night vision off
CameraAvStreamManagement.update {
  setNightVision(CameraAvStreamManagementTrait.TriStateAutoEnum.Off)
}

Mengubah kecerahan LED status

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

// Set the LED brightness to high
cameraAvStreamManagement.update {
  setStatusLightBrightness(CameraAvStreamManagementTrait.ThreeLevelAutoEnum.High)
}

// Set the LED brightness to low
cameraAvStreamManagement.update {
  setStatusLightBrightness(CameraAvStreamManagementTrait.ThreeLevelAutoEnum.Low)
}

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 dasar, untuk menyetel area tampilan video kamera, perbarui atribut viewport dari sifat CameraAvStreamManagement dengan ViewportStruct, menggunakan fungsi Kotlin setViewport bawaan:

cameraAvStreamManagement
  .update { setViewport(
    CameraAvStreamManagementTrait.ViewportStruct(
      x1 = horizontalRange.rangeStart.roundToInt().toUShort(),
      x2 = horizontalRange.rangeEnd.roundToInt().toUShort(),
      y1 = verticalRange.rangeStart.roundToInt().toUShort(),
      y2 = verticalRange.rangeEnd.roundToInt().toUShort(),
    )
) }

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 PushAvStreamTransport untuk setiap perangkat.

Sensitivitas aktivasi hanya dapat disetel ke nilai berikut:

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

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

// Create a struct with the new wake-up sensitivity
val toUpdate =  TransportOptionsStruct(
  triggerOptions =
    TransportTriggerOptionsStruct(
      motionSensitivity =
        OptionalValue.present(wakeUpSensitivity.toUByte())
    )
  )

// Get the configurations for active connections
val connections  = pushAvStreamTransport.findTransport().transportConfigurations
  // Update all recording streams with the new transport options.
  for (connection in connections) {
    if (connection.transportOptions.getOrNull()?.streamUsage == StreamUsageEnum.Recording) {
      trait.modifyPushTransport(
        connectionId = connection.connectionId,
        transportOptions = toUpdate,
      )
    }
  }

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 PushAvStreamTransport untuk setiap perangkat.

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

// Create a struct with the new max event length
// where maxDuration is the length in seconds
val toUpdate =  TransportOptionsStruct(
  triggerOptions =
    TransportTriggerOptionsStruct(
      motionTimeControl =
        OptionalValue.present(
          TransportMotionTriggerTimeControlStruct(maxDuration = it.toUInt())
        )
    )
  )

// Get the configurations for active connections
val connections  = pushAvStreamTransport.findTransport().transportConfigurations
  // Update all recording streams with the new transport options.
  for (connection in connections) {
    if (connection.transportOptions.getOrNull()?.streamUsage == StreamUsageEnum.Recording) {
      trait.modifyPushTransport(
        connectionId = connection.connectionId,
        transportOptions = toUpdate,
      )
    }
  }

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 Chime:

// Get a list of chimes and identify the currently selected one
private val doorbellChimeTraitFlow: Flow =
    device.traitFromType(Chime, GoogleDoorbellDevice)
val chimeSounds = doorbellChimeTraitFlow.first().installedChimeSounds ?: emptyList()

Kemudian, perbarui atribut selectedChime dari trait Chime menggunakan fungsi Kotlin setSelectedChime bawaan:

// Set the chime using the chimeId from the installed list
chimeSounds.firstOrNull { it.name == name }?.let { setSelectedChime(it.chimeId) }

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 Chime menggunakan fungsi Kotlin setExternalChime bawaan:

// Indicate the external chime is mechanical
chime.update {
  setExternalChime(ChimeTrait.ExternalChimeType.Mechanical)
}

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 bel eksternal, perbarui atribut externalChimeDurationSeconds dari trait Chime menggunakan fungsi Kotlin setExternalChimeDurationSeconds bawaan:

// Change the external chime duration
chime.update {
  setExternalChimeDurationSeconds(newDuration.toUShort())
}