Panduan perangkat kamera untuk Android

Jenis perangkat Kamera diimplementasikan menggunakan tiga karakteristik: PushAvStreamTransport, yang menangani transpor streaming audio dan video menggunakan protokol berbasis push, WebRtcLiveView, yang memberikan kemampuan untuk mengontrol livestream dan talkback, serta CameraSnapshot, yang menyediakan snapshot pratinjau yang di-cache dan pengambilan snapshot live.

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

Mendapatkan informasi dasar tentang perangkat

   Diimplementasikan di Aplikasi Contoh untuk Android   

Karakteristik BasicInformation mencakup informasi seperti nama vendor, ID vendor, ID produk, nama produk (termasuk informasi model), dan versi software 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}")
    }

Mendapatkan nomor seri

Untuk mendapatkan nomor seri perangkat, gunakan perintah GetSerialNumber dari trait ExtendedBasicInformation. Contoh berikut menunjukkan cara menyimpan nomor seri dalam variabel bernama serialNumber:

val basicInfo: ExtendedBasicInformation = device.getTrait(ExtendedBasicInformation)
val serialNumber = basicInfo.getSerialNumber().serialNumber

Mendapatkan waktu terbaru kontak cloud perangkat

Untuk menemukan waktu terbaru saat perangkat melakukan kontak dengan cloud, gunakan atribut lastContactTimestamp dari karakteristik ExtendedGeneralDiagnostics:

fun getLastContactTimeStamp(trait: ExtendedGeneralDiagnostics): java.time.Instant {
  val timestamp = trait.lastContactTimestamp
  return Instant.ofEpochSecond(timestamp.toLong())
}

Setelan jenis pemasangan kamera

Trait Mount berisi setelan dudukan kamera dan informasi status. Anda dapat membaca atribut seperti status pemasangan, jenis deteksi, dan nama jenis pemasangan. Selain itu, Anda dapat menggunakan karakteristik Mount untuk mengganti konfigurasi jenis pemasangan default.

// Get the Mount trait
val mountTrait: Mount = device.getTrait(Mount)

// Read the current mount state and detection type
val mountState = mountTrait.mountState
val mountDetectionType = mountTrait.mountDetectionType

// Read the current mount type name
val mountTypeName = mountTrait.mountTypeName

// Update the mount type override
mountTrait.update {
  setMountTypeOverride(MountTrait.MountTypeOverrideEnum.Official)
}

Memeriksa konektivitas untuk 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 karakteristik di perangkat tersebut.

val cameraConnectivity = cameraDevice.metadata.sourceConnectivity.connectivityState

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

Mendapatkan alamat IP perangkat

Untuk menemukan alamat IP perangkat, gunakan atribut networkInterfaces dari karakteristik GeneralDiagnostics. Alamat ditampilkan sebagai array byte, yang dapat Anda format menjadi string IPv4 atau IPv6 standar:

val ipAddresses =
  trait.networkInterfaces?.flatMap { networkInterface ->
    (networkInterface.ipv4Addresses + networkInterface.ipv6Addresses).mapNotNull { bytes ->
      try {
        java.net.InetAddress.getByAddress(bytes).hostAddress
      } catch (e: java.net.UnknownHostException) {
        null
      }
    }
  } ?: emptyList()

Memulai livestream

   Diimplementasikan di Aplikasi Contoh untuk Android   

Untuk memulai livestream, kirim string Session Description Protocol (SDP) ke metode startLiveView() pada karakteristik 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(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)

Memperpanjang livestream

   Diimplementasikan di Aplikasi Contoh untuk Android   

Livestream memiliki durasi preset yang akan berakhir setelahnya. 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

   Diimplementasikan di Aplikasi Contoh untuk Android   

Untuk memulai talkback, panggil metode startTalkback() pada 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)
  }
}

Mengelola livestream

Menyesuaikan kualitas livestream berguna untuk mengoptimalkan penggunaan bandwidth berdasarkan konteks tampilan klien (misalnya, beralih ke resolusi yang lebih rendah saat menampilkan kotak pratinjau yang lebih kecil, tampilan petak, atau mode picture-in-picture).

Mengubah kualitas secara dinamis menggunakan karakteristik WebRtcLiveView akan secara khusus mengelola resolusi sesi livestream aktif pada klien tertentu. Hal ini tidak sama dengan mengonfigurasi setelan penggunaan bandwidth di seluruh perangkat secara langsung di perangkat, yang akan memengaruhi semua penonton serentak dan kualitas rekaman video historis yang disimpan ke cloud.

Contoh berikut menunjukkan cara mengambil dan memperbarui kualitas livestream untuk perangkat:

• Mengambil opsi kualitas yang didukung: Dapatkan resolusi streaming yang tersedia dan didukung oleh perangkat. Kode ini mengkueri atribut supportedQualityHints pada karakteristik WebRtcLiveView di alur jenis perangkat dan mengekspos kualitas yang didukung sebagai StateFlow yang berisi daftar nilai QualityHint (seperti QUALITY_HINT_SD, QUALITY_HINT_HD, QUALITY_HINT_FHD, QUALITY_HINT_QHD, atau QUALITY_HINT_UHD).

• Mengubah kualitas livestream: Terapkan QualityHint yang dipilih untuk mengubah resolusi streaming livestream yang aktif (misalnya, beralih dari Definisi Standar ke Definisi Tinggi). Fungsi changeQuality me-resolve karakteristik livestreaming perangkat dan memanggil changeLiveViewQuality dengan mediaSessionId yang aktif dan konfigurasi QualityHint yang dipilih.

// Assuming you have a HomeDevice instance 'device'
val availableQualityHints: StateFlow<List> =
    device.type(GoogleCameraDevice)
        .trait(WebRtcLiveView)
        .map { trait -> 
            trait?.supportedQualityHints ?: emptyList() 
        }
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(), emptyList())

// Assuming you have a HomeDevice instance 'device'
suspend fun changeQuality(mediaSessionId: String, qualityHint: QualityHint) {
    // Get the trait from the device
    val trait = device.type(GoogleCameraDevice).trait(WebRtcLiveView).first() ?: return
    try {
        trait.changeLiveViewQuality(mediaSessionId, qualityHint)
    } catch (e: Exception) {
        // Handle error
    }
}

Mengaktifkan dan menonaktifkan kemampuan perekaman

Untuk mengaktifkan kemampuan perekaman kamera, teruskan TransportStatusEnum.Active ke metode setTransportStatus() pada karakteristik PushAvStreamTransport. Untuk menonaktifkan kemampuan perekaman, teruskan TransportStatusEnum.Inactive. Dalam contoh berikut, kita menggabungkan panggilan ini dalam satu panggilan yang menggunakan Boolean untuk mengalihkan 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. Saat 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 juga 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 memeriksanya adalah dengan 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
    }
}

Mengambil snapshot kamera

   Diimplementasikan di Aplikasi Contoh untuk Android   

Gunakan karakteristik CameraSnapshot untuk mengambil snapshot gambar statis dari kamera. Snapshot ini berguna untuk beberapa skenario:

• Sebagai kartu placeholder di UI saat livestream WebRTC sedang dimuat.
• Sebagai gambar pratinjau statis yang diupgrade ke livestream setelah interaksi pengguna.
• Sebagai kanvas latar belakang untuk menggambar dan mengonfigurasi zona aktivitas kustom.

Karakteristik CameraSnapshot menawarkan dua cara untuk mengambil snapshot, bergantung pada apakah Anda memerlukan snapshot yang di-cache untuk rendering cepat atau snapshot live on-demand.

Mendapatkan snapshot pratinjau yang di-cache

Snapshot pratinjau adalah gambar yang di-cache yang dapat diambil SDK tanpa mengaktifkan kamera. Ini adalah metode tercepat untuk mengambil gambar statis dan ideal untuk halaman ringkasan kamera atau petak dasbor.

Untuk mendapatkan snapshot pratinjau, baca atribut karakteristik preview_image_url:

// Get a flow of the CameraSnapshot trait
val cameraSnapshotFlow: Flow<CameraSnapshot?> = cameraDevice
  .type(GoogleCameraDevice)
  .trait(CameraSnapshot)

// Get the current trait state
val cameraSnapshot = cameraSnapshotFlow.firstOrNull()
if (cameraSnapshot != null) {
  val previewImageUrl = cameraSnapshot.previewImageUrl
  // Load the preview image from the URL
} else {
  // CameraSnapshot trait not supported on this device
}

Bergantung pada konfigurasi dan aktivitas kamera, URL pratinjau mengarah ke gambar yang di-cache yang dihasilkan dari rekaman video terbaru (I-frame pertama dari fragmen video terbaru) atau snapshot yang diupload secara berkala oleh kamera.

Untuk menunjukkan keaktualan gambar, cloud Google Home menyematkan header X-Home-Image-Captured-At dalam gambar JPEG/PNG yang disajikan, yang diformat dalam UTC. Anda dapat mengurai header ini di sisi klien untuk menampilkan usia snapshot dalam aplikasi.

Mendapatkan snapshot live on-demand

Untuk perjalanan pengguna yang memerlukan tayangan live kamera saat ini—seperti menyiapkan Zona Aktivitas—Anda dapat meminta snapshot live. Memicu snapshot live akan menginstruksikan kamera untuk aktif, mengambil frame baru, dan menguploadnya ke cloud.

Untuk meminta snapshot langsung, gunakan perintah getLiveSnapshot():

try {
  val response = cameraSnapshot.getLiveSnapshot()
  val snapshotUrl = response.snapshotUrl
  // Load the live snapshot image from the URL
} catch (e: Exception) {
  Log.e("CameraSnapshot", "Failed to get live snapshot: ${e.message}")
}

Mengautentikasi permintaan snapshot

   Diimplementasikan di Aplikasi Contoh untuk Android   

Semua URL snapshot mengarah ke media yang aman dan memerlukan token OAuth 2.0 untuk cakupan Home API v2. Untuk mendownload dan merender gambar, token OAuth harus diinjeksikan sebagai token Bearer di header Authorization permintaan HTTP Anda.

Contoh berikut menunjukkan cara mengonfigurasi permintaan jaringan yang aman untuk mendownload snapshot:

import android.graphics.Bitmap
import android.graphics.BitmapFactory
import java.io.IOException
import java.net.HttpURLConnection
import java.net.URL
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext

/**
 * Downloads a snapshot from a URL using an OAuth access token.
 */
suspend fun loadSnapshotImage(urlString: String, oauthToken: String): Bitmap? =
  withContext(Dispatchers.IO) {
    var connection: HttpURLConnection? = null
    try {
      val url = URL(urlString)
      connection = url.openConnection() as HttpURLConnection
      // 1. Configure the HTTP GET request with the Bearer token
      connection.setRequestProperty("Authorization", "Bearer $oauthToken")

      // 2. Fetch the image data
      if (connection.responseCode == HttpURLConnection.HTTP_OK) {
        connection.inputStream.use { inputStream ->
          BitmapFactory.decodeStream(inputStream)
        }
      } else {
        null
      }
    } catch (e: IOException) {
      e.printStackTrace()
      null
    } finally {
      connection?.disconnect()
    }
  }

Setelan baterai

Berbagai setelan baterai dapat dikontrol melalui Home API.

Menyetel preferensi penggunaan baterai

Dengan menyetel keseimbangan energi, Anda dapat mengonfigurasi kompromi antara masa pakai baterai dan performa untuk perangkat. Anda dapat membuat berbagai profil baterai, seperti "Diperpanjang", "Seimbang", dan "Performa", serta beralih di antaranya.

Fitur ini diimplementasikan dengan memperbarui atribut currentEnergyBalance dari trait 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 adalah 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 karakteristik 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 karakteristik PowerSource. 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"
}

Mendapatkan sumber daya

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

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

Periksa apakah baterai perlu diganti

Atribut batReplaceability menunjukkan apakah baterai tidak dapat diganti, dapat diganti oleh pengguna, atau dapat diganti oleh pabrik.

Atribut batReplacementNeeded dari karakteristik PowerSource memberi tahu Anda apakah baterai perlu diganti.

// Get the battery replacement status
val batteryStatus = powerSourceTrait.batReplacementNeeded

if (batteryStatus) {
  println("Replace the battery.")
}

Jika baterai dapat diganti oleh pengguna, batReplacementDescription akan menjelaskan baterai, termasuk informasi seperti faktor bentuk, kimia, dan produsen pilihan.

Setelan audio

Berbagai setelan audio dapat dikontrol melalui Home API.

Mengaktifkan atau menonaktifkan mikrofon

Untuk mengaktifkan atau menonaktifkan mikrofon perangkat, perbarui atribut microphoneMuted pada karakteristik 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 rekaman audio di perangkat, perbarui atribut recordingMicrophoneMuted pada karakteristik 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 karakteristik CameraAvStreamManagement menggunakan fungsi Kotlin setSpeakerVolumeLevel bawaan:

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

Setelan zona aktivitas

   Diimplementasikan di Aplikasi Contoh untuk Android   

Sifat ZoneManagement menyediakan antarmuka untuk mengelola region minat kustom (zona aktivitas) di perangkat kamera dan bel pintu. Zona ini digunakan untuk memfilter deteksi peristiwa (seperti gerakan orang atau kendaraan) ke area tertentu dalam ruang pandang perangkat.

Zona aktivitas dikonfigurasi oleh pengguna dalam aplikasi partner, sehingga mereka dapat menggambar zona di area tertentu dalam ruang pandang kamera. Zona yang ditentukan pengguna ini kemudian diterjemahkan ke dalam struktur yang digunakan oleh karakteristik ini. Untuk mengetahui informasi selengkapnya tentang cara kerja zona aktivitas, lihat Menyiapkan dan menggunakan Zona Aktivitas.

Zona aktivitas biasanya ditentukan menggunakan koordinat Kartesius 2D. Karakteristik ini menyediakan TwoDCartesianVertexStruct untuk verteks dan TwoDCartesianZoneStruct untuk definisi zona (nama, verteks, warna, dan penggunaan).

Memeriksa zona aktivitas

Untuk menampilkan zona aktivitas, periksa atribut zones dari karakteristik ZoneManagement.

// 1. Obtain the trait flow from the device
private val zoneManagementFlow: Flow =
  device.type(CAMERA_TYPE).flatMapLatest { it.trait(ZoneManagement) }

// 2. Map the flow to the list of zone structures
val activityZones: Flow<List<ZoneManagementTrait.ZoneInformationStruct>> =
  zoneManagementFlow.map { trait ->
    trait.zones ?: emptyList()
  }

Menambahkan zona aktivitas

Untuk membuat zona baru, gunakan perintah createTwoDCartesianZone. Perintah ini menggunakan TwoDCartesianZoneStruct, yang menentukan nama, verteks, warna, dan penggunaan zona.

Contoh berikut menunjukkan cara membuat zona bernama "Teras Depan" dengan empat verteks, berwarna salmon (#F439A0), dan digunakan untuk deteksi gerakan.

import com.google.home.google.ZoneManagement
import com.google.home.google.ZoneManagementTrait
import com.google.home.matter.serialization.OptionalValue

/**
 * Creates a custom activity zone named "Front Porch" with a salmon color
 * configured for motion detection.
 */
suspend fun createFrontPorchZone(zoneManagement: ZoneManagement) {
  // 1. Define the vertices for the zone (2D Cartesian coordinates)
  // Values are typically scaled to a maximum defined by the device's twoDCartesianMax attribute.
  val vertices =
    listOf(
      ZoneManagementTrait.TwoDCartesianVertexStruct(x = 260u, y = 422u),
      ZoneManagementTrait.TwoDCartesianVertexStruct(x = 1049u, y = 0u),
      ZoneManagementTrait.TwoDCartesianVertexStruct(x = 2048u, y = 0u),
      ZoneManagementTrait.TwoDCartesianVertexStruct(x = 2048u, y = 950u),
      ZoneManagementTrait.TwoDCartesianVertexStruct(x = 1630u, y = 1349u),
      ZoneManagementTrait.TwoDCartesianVertexStruct(x = 880u, y = 2048u),
      ZoneManagementTrait.TwoDCartesianVertexStruct(x = 0u, y = 2048u),
      ZoneManagementTrait.TwoDCartesianVertexStruct(x = 638u, y = 1090u)
    )

  // 2. Define the zone structure
  val newZone =
    ZoneManagementTrait.TwoDCartesianZoneStruct(
      name = "Front Porch",
      vertices = vertices,
      // Usage defines what the zone filters (for example, Motion, Person, Vehicle)
      use = listOf(ZoneManagementTrait.ZoneUseEnum.Motion),
      // Color is typically a hex string (for example, Salmon/Pink)
      color = OptionalValue.present("#F439A0")
    )

  try {
    // 3. Execute the command to add the zone to the device
    zoneManagement.createTwoDCartesianZone(newZone)
    println("Successfully created activity zone.")
  } catch (e: Exception) {
    // Handle potential HomeException or Timeout
    println("Failed to create activity zone: ${e.message}")
  }
}

Memperbarui zona aktivitas

Untuk memperbarui zona yang ada, gunakan perintah updateTwoDCartesianZone. Perintah ini memerlukan zoneId dan TwoDCartesianZoneStruct yang telah diupdate.

private suspend fun ZoneManagement.updateZone(
  zoneId: UShort,
  zone: ZoneManagementTrait.TwoDCartesianZoneStruct
) {
  // Execute the command to update the zone
  this.updateTwoDCartesianZone(zoneId = zoneId, zone = zone)
}

Menghapus zona aktivitas

Untuk menghapus zona, gunakan perintah removeZone dengan zoneId tertentu.

private suspend fun ZoneManagement.deleteZone(zoneId: UShort) {
  // Execute the command to remove the zone
  this.removeZone(zoneId = zoneId)
}

Pemicu Peristiwa Deteksi Suara

Karakteristik AvStreamAnalysis menyediakan antarmuka untuk mengelola pemicu deteksi peristiwa di perangkat kamera dan bel pintu. Meskipun pemicu berbasis penglihatan (seperti orang atau kendaraan) dapat bersifat spesifik per zona, pemicu terkait suara biasanya merupakan konfigurasi tingkat perangkat.

Jenis pemicu berikut tersedia untuk deteksi suara dengan EventTriggerTypeEnum:

Memeriksa status deteksi suara

Untuk menampilkan status deteksi suara saat ini kepada pengguna, Anda harus memeriksa apa yang didukung perangkat dan apa yang diaktifkan oleh hardware perangkat. Dua atribut yang perlu diperiksa adalah:

• supportedEventTriggers
• enabledEventTriggers

Dalam pengembangan Android menggunakan Kotlin Flow, Anda biasanya akan mengamati karakteristik AvStreamAnalysis dari HomeDevice.

// Example structure to store the
data class EventTriggerAttribute(val type: EventTriggerTypeEnum, val enabled: Boolean)

// 1. Obtain the trait flow from the device
private val avStreamAnalysisFlow: Flow<AvStreamAnalysis> =
  device.traitFromType(AvStreamAnalysis, CAMERA_TYPES.first { device.has(it) })

// 2. Map the flow to a list of sound event attributes
val soundEventTriggersState: Flow<List<EventTriggerAttribute>> =
  avStreamAnalysisFlow.map { trait ->
    // Get raw lists from the trait attributes
    val supported = trait.supportedEventTriggers ?: emptyList()
    val enabled = trait.enabledEventTriggers ?: emptyList()

    // Define sound-specific triggers to filter for
    val soundTypes = setOf(
      EventTriggerTypeEnum.Sound,
      EventTriggerTypeEnum.PersonTalking,
      EventTriggerTypeEnum.DogBark,
      EventTriggerTypeEnum.GlassBreak,
      EventTriggerTypeEnum.SmokeAlarm,
      EventTriggerTypeEnum.CoAlarm,
    )

    // Filter and associate status
    supported
      .filter { soundTypes.contains(it) }
      .map { type ->
        EventTriggerAttribute(
          type = type,
          enabled = enabled.contains(type)
        )
      }
  }

Memperbarui kumpulan pemicu yang diaktifkan

Untuk memperbarui kumpulan pemicu yang diaktifkan, gunakan perintah SetOrUpdateEventDetectionTriggers, yang menggunakan daftar struktur EventTriggerEnablement.

private suspend fun AvStreamAnalysis.updateEventTriggers(
  eventTriggers: List<EventTriggerAttribute>
) {
  val toUpdate = eventTriggers.map {
    EventTriggerEnablement(
      eventTriggerType = it.type,
      enablementStatus = if (it.enabled) {
        EnablementStatusEnum.Enabled
      } else {
        EnablementStatusEnum.Disabled
      },
    )
  }

  // Execute the command on the device
  setOrUpdateEventDetectionTriggers(toUpdate)
}

Mode perekaman

   Diimplementasikan di Aplikasi Contoh untuk Android   

Karakteristik RecordingMode menyediakan antarmuka untuk mengelola perilaku perekaman video dan gambar di perangkat kamera dan bel pintu. Fitur ini memungkinkan pengguna memilih antara perekaman nonstop, rekaman peristiwa penting, atau menonaktifkan perekaman sepenuhnya (hanya Tayangan Live).

RecordingModeEnum menentukan strategi perekaman yang tersedia:

Memeriksa mode perekaman

Untuk menampilkan konfigurasi perekaman saat ini, periksa atribut trait RecordingMode:

• supportedRecordingModes - Semua mode potensial
• availableRecordingModes - Mode yang dapat dipilih
• selectedRecordingMode - Mode aktif

// 1. Obtain the trait flow from the device
private val recordingModeTraitFlow: Flow =
    device.traitFromType(RecordingMode, CAMERA_TYPES.first { device.has(it) })

// 2. Map the flow to recording mode options
data class RecordingModeOptions(
    val recordingMode: RecordingModeTrait.RecordingModeEnum,
    val index: Int,
    val available: Boolean,
    val readableString: String,
)

private val recordingModeOptions: Flow<List> =
    recordingModeTraitFlow.map { trait ->
        val supported = trait.supportedRecordingModes?.map { it.recordingMode } ?: emptyList()
        val available = trait.availableRecordingModes?.map { it.toInt() } ?: emptyList()

        supported.withIndex().map { (index, mode) ->
            RecordingModeOptions(
                recordingMode = mode,
                index = index,
                available = available.contains(index),
                readableString = mode.toReadableString(),
            )
        }
    }

Mengubah mode perekaman

Sebelum mengupdate, pastikan indeks yang dipilih dari atribut supportedRecordingModes ada di atribut availableRecordingModes.

Untuk memperbarui mode yang dipilih, gunakan fungsi setSelectedRecordingMode, dengan meneruskan indeks mode yang dipilih:

private suspend fun RecordingMode.updateRecordingMode(index: Int) {
    // Execute the command to update the selected mode
    this.setSelectedRecordingMode(index.toUByte())
}

Setelan lainnya

Berbagai setelan lainnya dapat dikontrol melalui Home API.

Mengubah orientasi gambar

Orientasi gambar kamera (video) dapat diputar. Video hanya dapat diputar 180 derajat.

Untuk mengubah orientasi gambar kamera, perbarui atribut imageRotation dari karakteristik CameraAvStreamManagement menggunakan fungsi Kotlin setImageRotation bawaan:

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

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

Mengaktifkan atau menonaktifkan night vision

Untuk mengaktifkan atau menonaktifkan night vision pada kamera, gunakan TriStateAutoEnum untuk memperbarui atribut nightVision dari karakteristik 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 karakteristik 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

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

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

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

Penentuan nilai untuk ViewportStruct bergantung pada UI dan implementasi kamera aplikasi. Pada tingkat yang sangat dasar, untuk menyetel area pandang video kamera, perbarui atribut viewport dari karakteristik 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(),
    )
) }

Mengaktifkan atau menonaktifkan analisis

Setiap perangkat dapat memilih untuk mengirim data analisis mendetail ke cloud Google Home (lihat Cloud Monitoring untuk Home API).

Untuk mengaktifkan analisis untuk perangkat, tetapkan properti analyticsEnabled dari ExtendedGeneralDiagnosticsTrait ke true. Saat Anda menetapkan analyticsEnabled, properti lain, logUploadEnabled, akan otomatis ditetapkan ke true, yang memungkinkan file log analisis diupload ke cloud Google Home.

// Enable analytics
extendedGeneralDiagnostics.update {
  setAnalyticsEnabled(true)
}

// Disable analytics
extendedGeneralDiagnostics.update {
  setAnalyticsEnabled(false)
}

Konfigurasi transportasi dan perekaman

Bagian ini membahas setelan yang terkait dengan kualitas streaming kamera dan pemicu peristiwa. Setelan ini dikelola oleh karakteristik PushAvStreamTransport.

Membaca setelan transportasi

Bagian ini menunjukkan cara mengambil konfigurasi saat ini dari perangkat kamera atau bel pintu. Fungsi ini mengambil karakteristik PushAvStreamTransport, menemukan koneksi spesifik yang digunakan untuk perekaman, lalu mengekstrak nilai saat ini untuk kualitas bandwidth, sensitivitas aktivasi, dan durasi peristiwa maksimum.

val trait: PushAvStreamTransport = device.getTrait(PushAvStreamTransport)
val connections = trait.findTransport().transportConfigurations

// Locate the connection designated for recording
val recordingConnection = connections.firstOrNull {
    it.transportOptions.getOrNull()?.streamUsage == StreamUsageEnum.Recording
}

val options = recordingConnection?.transportOptions?.getOrNull()

// 1. Bandwidth Quality (Video Stream ID)
val videoStreamId = options?.videoStreamId?.getOrNull()

// 2. Wake-up Sensitivity (Motion Sensitivity)
val wakeUpSensitivity = options?.triggerOptions?.motionSensitivity?.getOrNull()

// 3. Max Event Length (Motion Trigger Time Control)
val maxEventLength = options?.triggerOptions?.motionTimeControl?.getOrNull()?.maxDuration

Memperbarui setelan transportasi

Bagian ini menunjukkan cara mengubah setelan transportasi. Skrip ini membuat TransportOptionsStruct baru yang berisi nilai baru, lalu menggunakan perintah modifyPushTransport untuk mengirim setelan yang diperbarui ini kembali ke perangkat, sehingga menerapkannya ke koneksi perekaman yang ditemukan di langkah sebelumnya.

Untuk mengubah setelan ini, gunakan perintah modifyPushTransport dengan TransportOptionsStruct.

val toUpdate = TransportOptionsStruct(
    videoStreamId = OptionalValue.present(2u), // e.g., Max Quality
    triggerOptions = TransportTriggerOptionsStruct(
        motionSensitivity = OptionalValue.present(5u), // e.g., Medium
        motionTimeControl = OptionalValue.present(
            TransportMotionTriggerTimeControlStruct(maxDuration = 30u)
        )
    )
)

if (recordingConnection != null) {
    trait.modifyPushTransport(
        connectionId = recordingConnection.connectionId,
        transportOptions = toUpdate
    )
}

Menentukan kualitas bandwidth

Properti videoStreamId dari TransportOptionsStruct sesuai dengan konfigurasi streaming video tertentu.

Untuk mendapatkan streaming video yang didukung, lihat atribut allocatedVideoStreams, yang merupakan daftar VideoStreamStructs. dari karakteristik CameraAvStreamManagement untuk perangkat.

Menyesuaikan sensitivitas aktivasi perangkat

Properti motionSensitivity dari TransportTriggerOptionsStruct sesuai dengan nilai berikut:

Menyesuaikan durasi peristiwa maksimum

Properti maxDuration dari TransportMotionTriggerTimeControlStruct sesuai dengan durasi berikut (dalam detik):

• 10u, 15u, 30u, 60u, 120u, 180u

Mencabut akses perangkat

Untuk menghapus kamera dari struktur, panggil device.decommissionDevice(). Penonaktifan akan menampilkan layar konfirmasi yang dikelola Google kepada pengguna, yang memperingatkan bahwa semua histori video 24/7, histori peristiwa, klip, dan data galeri foto wajah yang dikenali yang direkam akan dihapus secara permanen di seluruh struktur.

Untuk mengetahui petunjuk mendetail dan contoh kode, lihat Menghapus perangkat.