Android için kamera cihazı kılavuzu

Kamera cihaz türü iki özellik kullanılarak uygulanır: PushAvStreamTransport, bu özellik, push tabanlı protokoller kullanarak ses ve video akışı aktarımını yönetir ve WebRtcLiveView, bu özellik, canlı yayınları ve talkback'i kontrol etme olanağı sağlar.

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.

Home API'leri Cihaz Türü Özellikler Kotlin Örnek Uygulaması Kullanım Örneği

Kamera

GoogleCameraDevice

home.matter.6006.types.0158

Sabit görüntü veya video çeken bir cihaz. Kameralarda erişilebilir canlı yayınlar, iki yönlü konuşma veya algılama etkinlikleri bulunabilir.

Zorunlu Özellikler
     google PushAvStreamTransport
     google WebRtcLiveView

Kamera

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(GoogleCameraDevice).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.

Resim yönünü değiştirme

Kamera görüntüsünün (video) yönü döndürülebilir. Video yalnızca 180 derece döndürülebilir.

Kameranın görüntü yönünü değiştirmek için yerleşik setImageRotation Kotlin işlevini kullanarak CameraAvStreamManagement özelliğinin imageRotation özelliğini güncelleyin:

// Change the camera's image orientation
val isRotated = false

cameraAvStreamManagement.update { setImageRotation(if (isRotated) 180.toUShort() else 0.toUShort()) }

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