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.

Mendapatkan informasi dasar tentang perangkat

Trait BasicInformation mencakup informasi seperti nama vendor, ID vendor, ID produk, nama produk (mencakup informasi model), versi software, dan nomor seri untuk perangkat:

// Get device basic information. All general information traits are on the RootNodeDevice type.
    device.type(RootNodeDevice).first().standardTraits.basicInformation?.let { basicInformation ->
        println("vendorName ${basicInformation.vendorName}")
        println("vendorId ${basicInformation.vendorId}")
        println("productId ${basicInformation.productId}")
        println("productName ${basicInformation.productName}")
        println("softwareVersion ${basicInformation.softwareVersion}")
        println("serialNumber ${basicInformation.serialNumber}")
    }

Memeriksa konektivitas perangkat

Konektivitas untuk perangkat sebenarnya diperiksa di tingkat jenis perangkat karena beberapa perangkat mendukung beberapa jenis perangkat. Status yang ditampilkan adalah kombinasi status konektivitas untuk semua fitur di perangkat tersebut.

val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState

Status PARTIALLY_ONLINE dapat diamati dalam kasus jenis perangkat campuran saat tidak ada konektivitas internet. Ciri standar Matter mungkin masih online karena perutean lokal, tetapi ciri berbasis cloud akan offline.

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 hitungan 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(trait: PushAvStreamTransport, isOn: Boolean) {
  if(isOn) {
    trait.setTransportStatus(TransportStatusEnum.Active)
  } else {
    trait.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(pushAvStreamTransport: PushAvStreamTransport) {
  return pushAvStreamTransport
    .currentConnections?.any { it.transportStatus == TransportStatusEnum.Active } ?: false
}

// 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(trait: PushAvStreamTransport) {
  return trait.findTransport().let {
      it.transportConfigurations.any { it.transportStatus == TransportStatusEnum.Active
    }
}

Setelan baterai

Berbagai setelan baterai dapat dikontrol melalui Home API.

Menyetel preferensi penggunaan baterai

Dengan menyetel keseimbangan energi, Anda dapat mengonfigurasi keseimbangan antara daya tahan baterai dan performa perangkat. Anda dapat membuat profil baterai yang berbeda, seperti "Diperpanjang", "Seimbang", dan "Performa", serta beralih di antara profil tersebut.

Fitur ini diterapkan dengan memperbarui atribut currentEnergyBalance dari sifat EnergyPreference. Atribut ini menerima indeks bilangan bulat yang sesuai dengan profil tertentu yang ditentukan dalam daftar energyBalances perangkat (misalnya, 0 untuk EXTENDED, 1 untuk BALANCED, dan 2 untuk PERFORMANCE).

Nilai null untuk currentEnergyBalance menunjukkan bahwa perangkat menggunakan profil kustom. Ini adalah status hanya baca.

Berikut ini contoh struktur yang akan digunakan atribut currentEnergyBalance, diikuti dengan cuplikan kode sebenarnya yang menggunakan atribut tersebut.

// Example energyBalances list
energy_balances: [
  {
    step: 0,
    label: "EXTENDED"
  },
  {
    step: 50,
    label: "BALANCED"
  },
  {
    step: 100,
    label: "PERFORMANCE"
  }
]

// The index parameter must be within the UByte range (0-255).
suspend fun setEnergyBalance(trait: EnergyPreference, index: Int) {
  trait.update { setCurrentEnergyBalance(index.toUByte()) }
}

// Setting the battery usage to more recording ie performance
setEnergyBalance(energyPreference, 2)

Mengaktifkan penghemat baterai otomatis

Untuk mengonfigurasi fitur ini, perbarui atribut currentLowPowerModeSensitivity dari sifat EnergyPreference. Atribut ini menggunakan indeks untuk memilih tingkat sensitivitas, dengan 0 biasanya mewakili Disabled dan 1 mewakili Enabled atau Automatic.

suspend fun setAutomaticBatterySaver(enable: Boolean, trait: EnergyPreference) {
  // 0 is Disabled, 1 is Enabled
  val value = if (enable) 1.toUByte() else 0.toUByte()
  trait.update { setCurrentLowPowerModeSensitivity(value) }
}

Mendapatkan status pengisian daya baterai

Untuk mendapatkan status pengisian daya perangkat saat ini (mengisi daya, terisi penuh, atau tidak mengisi daya), gunakan atribut batChargeState dari karakteristik PowerSource.

// Get the battery charging state
val batteryChargeState = powerSource.batChargeState

when (batteryChargeState) {
    PowerSourceTrait.BatChargeStateEnum.IsCharging -> "Charging"
    PowerSourceTrait.BatChargeStateEnum.IsAtFullCharge -> "Full"
    PowerSourceTrait.BatChargeStateEnum.IsNotCharging -> "Not Charging"
    else -> "Unknown"
}

Mendapatkan level baterai

Untuk mendapatkan level baterai saat ini, gunakan atribut batChargeLevel dari PowerSource trait. Levelnya adalah OK, Warning (rendah), atau Critical.

// Get the battery charge level
val batteryLevel = powerSourceTrait.batChargeLevel

when (batteryLevel) {
    PowerSourceTrait.BatChargeLevelEnum.OK -> "OK"
    PowerSourceTrait.BatChargeLevelEnum.Warning -> "Warning"
    PowerSourceTrait.BatChargeLevelEnum.Critical -> "Critical"
    else -> "Unknown"
}

Dapatkan sumber listrik

Untuk menentukan sumber listrik yang digunakan perangkat, gunakan atribut BatPresent dan wiredPresent dari karakteristik PowerSource.

  val trait: PowerSource
  val isWired = trait.wiredPresent
  val hasBattery = trait.batPresent

Setelan audio

Berbagai setelan audio 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 lainnya dapat dikontrol melalui Home API.

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 dari 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, hal 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 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, hal 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())
}

Mengaktifkan tema bunyi bel

Beberapa bel pintu mungkin memiliki bel yang hanya tersedia untuk pengguna dalam waktu terbatas. Misalnya, bunyi bel khusus untuk hari libur. Ini disebut tema bunyi.

Untuk melihat tema bel yang tersedia bagi pengguna, buat filter kotak waktu dan gunakan untuk memfilter hasil perintah getAvailableThemes() dari trait ChimeThemes. Tindakan ini akan menampilkan daftar tema yang tersedia, termasuk nama tema.

Contoh berikut menunjukkan cara memfilter daftar. Tema dianggap aktif jika waktu saat ini berada dalam waktu mulai dan berakhirnya (nilai startTimeSeconds dan endTimeSeconds, masing-masing). Jika waktu mulai tidak ditetapkan, perangkat dianggap aktif sejak awal waktu. Jika waktu berakhir tidak ditetapkan, waktu tersebut akan terus aktif tanpa batas. Jika keduanya tidak ada, tema akan selalu aktif.

// Get themes from the ChimeThemes trait
fun List<ChimeThemesTrait.ThemeStruct>.filterTimeboxedThemes():
    List<ChimeThemesTrait.ThemeStruct> {
  val now = timeSource.instant().epochSecond.toULong()
  return filter { chimeStruct: ChimeThemesTrait.ThemeStruct ->
    val startTime: ULong = chimeStruct.startTimeSeconds.getOrNull() ?: 0UL
    val endTime: ULong = chimeStruct.endTimeSeconds.getOrNull() ?: MAX_VALUE
    startTime <= now && now <= endTime
  }
}

val availableThemes =
  doorbellChimeThemesTraitFlow
    .first()
    .getAvailableThemes()
    .themes
    .filterTimeboxedThemes()

Setelah memiliki nama tema yang diinginkan, seperti Christmas, Anda dapat memilihnya menggunakan fungsi setSelectedTimeboxedThemeName() pada karakteristik ChimeThemes:

// Select a theme using the ChimeThemes trait
val themeToSelect = "Christmas"
if (themeToSelect in availableThemeNames) {
  doorbellChimeThemesTraitFlow.first().setSelectedTimeboxedThemeName(themeToSelect)
}