Android için kapı zili cihazı kılavuzu

Kapı zili cihaz türü iki özellik kullanılarak uygulanır: PushAvStreamTransport, which handles audio and video stream transport using push-based protocols, and WebRtcLiveView, which provides the ability to control livestreams and talkback.

Herhangi bir özelliği kullanmadan veya özellikleri güncellemeye çalışmadan önce cihazın özellik ve komut desteğini mutlaka kontrol edin. Daha fazla bilgi için Androidcihazlarını kontrol etme başlıklı makaleye bakın.

Cihaz hakkında temel bilgileri edinme

BasicInformation özelliği; satıcı adı, satıcı kimliği, ürün kimliği, ürün adı (model bilgilerini içerir), yazılım sürümü ve cihazın seri numarası gibi bilgileri içerir:

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

Bir cihazın bağlantısını kontrol etme

Bazı cihazlar birden fazla cihaz türünü desteklediğinden, bir cihazın bağlantısı aslında cihaz türü düzeyinde kontrol edilir. Döndürülen durum, söz konusu cihazdaki tüm özelliklerin bağlantı durumlarının birleşimidir.

val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState

İnternet bağlantısı olmadığında karışık cihaz türleri söz konusuysa PARTIALLY_ONLINE durumu gözlemlenebilir. Matter standart özellikleri, yerel yönlendirme nedeniyle hâlâ online olabilir ancak bulut tabanlı özellikler offline olur.

Canlı yayın başlatma

Canlı yayın başlatmak için Oturum Açıklama Protokolü (SDP) dizesini WebRtcLiveView özelliğinin startLiveView() yöntemine gönderin. Bu yöntem, üç değer içeren bir WebRtcLiveViewTrait.StartLiveViewCommand.Response döndürür:

• Oturumun SDP'si.
• Oturum süresi (saniye cinsinden).
• Oturumu uzatmak veya sonlandırmak için kullanılabilecek oturum kimliği.

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)

Canlı yayını uzatma

Canlı yayınların önceden belirlenmiş bir süresi vardır ve bu süre sonunda sona erer. Etkin bir akışın süresini uzatmak için WebRtcLiveView.extendLiveView() yöntemini kullanarak uzatma isteğinde bulunun:

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

TalkBack'i başlatma ve durdurma

TalkBack'i başlatmak için WebRtcLiveView özelliğinin startTalkback() yöntemini çağırın. Durdurmak için stopTalkback() simgesini kullanın.

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

Kayıt özelliğini etkinleştirme ve devre dışı bırakma

Kameranın kayıt özelliğini etkinleştirmek için TransportStatusEnum.Active öğesini PushAvStreamTransport özelliğinin setTransportStatus() yöntemine iletin. Kayıt özelliğini devre dışı bırakmak için bu işlevi geçirin TransportStatusEnum.Inactive. Aşağıdaki örnekte, bu aramaları, kayıt özelliğini etkinleştirmek veya devre dışı bırakmak için Boolean kullanan tek bir aramada sarmalıyoruz:

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

Kameranın kayıt özelliğini etkinleştirmek veya devre dışı bırakmak, kamera videosunu açmak veya kapatmakla aynıdır. Kameranın videosu açıkken kayıt yapılır (etkinlikler ve ilgili klipler için).

Kayıt özelliği devre dışı bırakıldığında (kamera videosu kapalıyken):

• Kamera, connectivityState cihaz türüne göre çevrimiçi olarak görünmeye devam edebilir.
• Canlı yayına erişilemiyor ve kamera herhangi bir bulut etkinliği algılamıyor.

Kayıt özelliğinin etkin olup olmadığını kontrol etme

Bir kameranın kayıt özelliğinin etkin olup olmadığını belirlemek için herhangi bir bağlantının etkin olup olmadığını kontrol edin. Aşağıdaki örnekte bu işlemi gerçekleştirmek için iki işlev tanımlanmaktadır:

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

Kontrol etmenin bir diğer yolu da findTransport() işlevini bir yüklemle kullanmaktır:

// Fetch the current connections
suspend fun queryRecordModeState(trait: PushAvStreamTransport) {
  return trait.findTransport().let {
      it.transportConfigurations.any { it.transportStatus == TransportStatusEnum.Active
    }
}

Pil ayarları

Çeşitli pil ayarları, Home API'leri aracılığıyla kontrol edilebilir.

Pil kullanım tercihini ayarlama

Enerji dengesini ayarlayarak bir cihazın pil ömrü ile performansı arasındaki dengeyi yapılandırabilirsiniz. "Uzatılmış", "Dengeli" ve "Performans" gibi farklı pil profilleri oluşturabilir ve bunlar arasında geçiş yapabilirsiniz.

Bu özellik, EnergyPreference özelliğinin currentEnergyBalance özelliği güncellenerek uygulanır. Bu özellik, cihazın energyBalances listesinde tanımlanan belirli bir profile karşılık gelen bir tam sayı dizini kabul eder (örneğin, EXTENDED için 0, BALANCED için 1 ve PERFORMANCE için 2).

currentEnergyBalance için null değeri, cihazın özel profil kullandığını gösterir. Bu, salt okunur bir durumdur.

Aşağıda, currentEnergyBalance özelliğinin kullanacağı bir yapı örneği ve ardından özelliği kullanan asıl kod snippet'i gösterilmektedir.

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

Otomatik pil tasarrufunu açma

Bu özelliği yapılandırmak için EnergyPreference özelliğinin currentLowPowerModeSensitivity özelliğini güncelleyin. Bu özellik, hassasiyet düzeyini seçmek için bir dizin kullanır. Burada 0 genellikle Disabled'i, 1 ise Enabled veya Automatic'i temsil eder.

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

Pil şarj durumunu alma

Cihazın mevcut şarj durumunu (şarj oluyor, tamamen şarj oldu veya şarj olmuyor) almak için PowerSource özelliğinin batChargeState özelliğini kullanın.

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

Pil seviyesini alma

Mevcut pil seviyesini almak için batChargeLevel özelliğini kullanın. PowerSource özelliği. Düzey OK, Warning (düşük) veya Critical'dir.

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

Güç kaynağını alma

Cihazın kullandığı güç kaynağını belirlemek için BatPresent ve wiredPresent özelliklerini kullanın.PowerSource

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

Ses ayarları

Çeşitli ses ayarları, Home API'leri aracılığıyla kontrol edilebilir.

Mikrofonu açma veya kapatma

Cihazın mikrofonunu açmak veya kapatmak için yerleşik setMicrophoneMuted Kotlin işlevini kullanarak CameraAvStreamManagement özelliğinin microphoneMuted özelliğini güncelleyin:

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

Ses kaydını etkinleştirme veya devre dışı bırakma

Cihazda ses kaydını etkinleştirmek veya devre dışı bırakmak için yerleşik setRecordingMicrophoneMuted Kotlin işlevini kullanarak CameraAvStreamManagement özelliğinin recordingMicrophoneMuted özelliğini güncelleyin:

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

Hoparlörün ses düzeyini ayarlama

Cihazın hoparlör sesini ayarlamak için yerleşik setSpeakerVolumeLevel Kotlin işlevini kullanarak CameraAvStreamManagement özelliğinin speakerVolumeLevel özelliğini güncelleyin:

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

Diğer ayarlar

Diğer çeşitli ayarlar Home API'leri aracılığıyla kontrol edilebilir.

Gece görüşünü açma veya kapatma

Kamerada gece görüşünü açmak veya kapatmak için yerleşik setNightVision Kotlin işlevini kullanarak CameraAvStreamManagement özelliğinin TriStateAutoEnum nightVision özelliğini güncelleyin:

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

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

Durum LED'inin parlaklığını değiştirme

Durum LED'inin parlaklığını değiştirmek için yerleşik setStatusLightBrightness Kotlin işlevini kullanarak CameraAvStreamManagement özelliğinin statusLightBrightness özelliğini güncellemek üzere ThreeLevelAutoEnum kullanın:

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

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

Kamera görüntü alanını değiştirme

Kamera görüntü alanı, Nest kamera videosunu yakınlaştırma ve iyileştirme başlıklı destek makalesinde açıklanan yakınlaştırma ve kırpma özelliğiyle aynıdır.

Görünüm alanı, dört değer içeren bir ViewportStruct içinde tanımlanır. Bu değerler, görünüm alanının koordinatları olarak kullanılır. Koordinatlar şu şekilde tanımlanır:

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

ViewportStruct değerlerinin belirlenmesi, uygulamanın kullanıcı arayüzüne ve kamera uygulamasına bağlıdır. En temel düzeyde, kamera videosunun görünüm alanını ayarlamak için CameraAvStreamManagement özelliğinin viewport özelliğini ViewportStruct ile güncelleyin. Bunu yaparken yerleşik setViewport Kotlin işlevini kullanın:

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

Cihazın uyandırılma hassasiyetini ayarlama

Cihazın uyanma hassasiyeti, cihazın etkinliği algılayabileceği aralığı azaltarak ve bu etkinliği algıladıktan sonra uyanma süresini artırarak pil tasarrufu yapmak için kullanılır.

Home API'lerinde bu, cihazın transportOptions içindeki triggerOptions öğesinin motionSensitivity özelliği kullanılarak ayarlanabilir. Bu seçenekler her cihaz için PushAvStreamTransport özelliğinde tanımlanır.

Uyandırma hassasiyeti yalnızca aşağıdaki değerlere ayarlanabilir:

• 1 = Düşük
• 5 = Orta
• 10 = Yüksek

Güncelleme işlemi, findTransport komutunu kullanarak etkin kayıt akışlarının araç yapılandırmasını bulup modifyPushTransport komutunu kullanarak yapılandırmayı yeni hassasiyet değeriyle değiştirmektir:

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

Maksimum etkinlik süresini ayarlama

Maksimum etkinlik süresi, kameranın bir etkinlik için klip kaydedeceği süredir. Bu, Home API'leri aracılığıyla cihaz başına GHA üzerinden olduğu gibi saniyelik aralıklarla aynı uzunluklarda yapılandırılabilir:

• 10 saniye
• 15 saniye
• 30 saniye
• 60 saniye (1 dakika)
• 120 saniye (2 dakika)
• 180 saniye (3 dakika)

Home API'lerinde bu, cihazın transportOptions içindeki triggerOptions öğesinin motionTimeControl özelliği kullanılarak ayarlanabilir. Bu seçenekler her cihaz için PushAvStreamTransport özelliğinde tanımlanır.

Güncelleme işlemi için findTransport komutunu kullanarak etkin kayıt akışlarının aktarım yapılandırmasını bulun, ardından modifyPushTransport komutunu kullanarak yapılandırmayı yeni etkinlik uzunluğu değeriyle değiştirin:

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

Zil ayarları

Çeşitli kapı zili sesi ayarları, Home API'leri aracılığıyla kontrol edilebilir.

Zil sesini değiştirme

Kapı zili sesini değiştirmek için önce Chime özelliğinin installedChimeSounds özelliğini kullanarak cihaza yüklenen zili seslerinin listesini alın:

// 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()

Ardından, yerleşik setSelectedChime Kotlin işlevini kullanarak Chime özelliğinin selectedChime özelliğini güncelleyin:

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

Harici bir zil kullanma

Kapı zili, evde kurulu mekanik zil gibi harici bir zil kullanacak şekilde yapılandırılabilir. Harici zil sesinde olası hasarları önlemek için bu ayar kapı zili kurulumu sırasında yapılandırılmalıdır.

Hangi tür harici zil sesinin yüklendiğini belirtmek için yerleşik setExternalChime Kotlin işlevini kullanarak Chime özelliğinin externalChime özelliğini güncellemek üzere ExternalChimeType kullanın:

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

Harici zil süresini değiştirme

Harici bir zilin çalma süresi (saniye cinsinden) Home API'leri aracılığıyla yapılandırılabilir. Harici zil sesi, zil sesi süresini destekliyorsa kullanıcı bu süreyi yapılandırmak isteyebilir.

Burada ayarlanan değer, harici zilin özelliklerine ve önerilen zil süresine bağlıdır.

Harici zil sesinin süresini değiştirmek için yerleşik setExternalChimeDurationSeconds Kotlin işlevini kullanarak Chime özelliğinin externalChimeDurationSeconds özelliğini güncelleyin:

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

Çan temasını etkinleştirme

Bazı kapı zillerinde, yalnızca sınırlı bir süre için kullanılabilen zil sesleri olabilir. Örneğin, tatillere özel zil sesleri. Bunlara zil sesi temaları denir.

Bir kullanıcı için hangi zil sesi temalarının kullanılabildiğini görmek istiyorsanız bir zaman kutusu filtresi oluşturun ve getAvailableThemes() komutunun sonuçlarını ChimeThemes özelliğinden filtrelemek için bu filtreyi kullanın. Bu işlem, tema adları da dahil olmak üzere kullanılabilir temaların listesini döndürür.

Aşağıdaki örnekte listenin nasıl filtreleneceği gösterilmektedir. Geçerli saat, temanın başlangıç ve bitiş saatleri (sırasıyla startTimeSeconds ve endTimeSeconds değerleri) arasındaysa tema etkin olarak kabul edilir. Başlangıç saati ayarlanmamışsa başlangıçtan itibaren etkin kabul edilir. Bitiş zamanı ayarlanmamışsa süresiz olarak etkin kalır. İkisi de eksikse tema her zaman etkindir.

// 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()

İstediğiniz temanın adını (ör. Christmas) öğrendikten sonra ChimeThemes özelliğinde setSelectedTimeboxedThemeName() işlevini kullanarak temayı seçebilirsiniz:

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