Guide des caméras pour Android

Le type d'appareil "Caméra" est implémenté à l'aide de deux traits : PushAvStreamTransport, qui gère le transport des flux audio et vidéo à l'aide de protocoles de type push, et WebRtcLiveView, qui permet de contrôler les flux en direct et la fonctionnalité de communication bidirectionnelle.

Assurez-vous toujours qu'un appareil prend en charge les attributs et les commandes nécessaires avant d'utiliser une fonctionnalité ou de tenter de mettre à jour des attributs. Pour en savoir plus, consultez Contrôler les appareils surAndroid.

Obtenir des informations de base sur un appareil

Le trait BasicInformation inclut des informations telles que le nom du fournisseur, son ID, l'ID du produit, le nom du produit (y compris les informations sur le modèle) et la version logicielle d'un appareil :

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

Obtenir le numéro de série

Pour obtenir le numéro de série de l'appareil, utilisez la commande GetSerialNumber du trait ExtendedBasicInformation. L'exemple montre comment enregistrer le numéro de série dans une variable nommée serialNumber :

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

Obtenir la dernière heure de contact de l'appareil avec le cloud

Pour trouver la dernière heure à laquelle l'appareil a été en contact avec le cloud, utilisez l'attribut lastContactTimestamp du trait ExtendedGeneralDiagnostics :

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

Paramètres du type de support de caméra

Le trait Mount contient les paramètres de fixation de la caméra et des informations sur son état. Vous pouvez lire des attributs tels que l'état de montage, le type de détection et le nom du type de montage. De plus, vous pouvez utiliser le trait Mount pour remplacer la configuration du type de montage par défaut.

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

Vérifier la connectivité d'un appareil

La connectivité d'un appareil est en fait vérifiée au niveau du type d'appareil, car certains appareils sont compatibles avec plusieurs types d'appareils. L'état renvoyé est une combinaison des états de connectivité de tous les traits de cet appareil.

val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState

Un état PARTIALLY_ONLINE peut être observé dans le cas de types d'appareils mixtes en l'absence de connectivité Internet. Les caractéristiques standards Matter peuvent toujours être en ligne en raison du routage local, mais les caractéristiques basées sur le cloud seront hors connexion.

Obtenir l'adresse IP de l'appareil

Pour trouver l'adresse IP de l'appareil, utilisez l'attribut networkInterfaces du trait GeneralDiagnostics. Les adresses sont renvoyées sous forme de tableaux d'octets, que vous pouvez mettre en forme en chaînes IPv4 ou IPv6 standards :

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

Lancer un flux en direct

Pour lancer une diffusion en direct, envoyez la chaîne SDP (Session Description Protocol) à la méthode startLiveView() du trait WebRtcLiveView, qui renvoie un WebRtcLiveViewTrait.StartLiveViewCommand.Response contenant trois valeurs :

• SDP de la session
• Durée de la session en secondes
• ID de la session, qui peut être utilisé pour la prolonger ou y mettre fin

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)

Prolonger un flux en direct

Les flux en direct ont une durée prédéfinie au terme de laquelle ils expirent. Pour prolonger la durée d'un flux actif, utilisez la méthode 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
}

Démarrer et arrêter la conversation bidirectionnelle

Pour démarrer la conversation bidirectionnelle, appelez la méthode startTalkback() du trait WebRtcLiveView. Pour arrêter, utilisez 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)
  }
}

Gérer une diffusion en direct

Ajuster la qualité de la diffusion en direct est utile pour optimiser l'utilisation de la bande passante en fonction du contexte de visionnage du client (par exemple, en passant à une résolution inférieure lors de l'affichage d'une vignette d'aperçu plus petite, d'un mode Grille ou d'un mode Picture-in-picture).

La modification dynamique de la qualité à l'aide du trait WebRtcLiveView gère spécifiquement la résolution de la session de diffusion en direct active sur un client particulier. Il ne s'agit pas de la même chose que de configurer un paramètre d'utilisation de la bande passante à l'échelle de l'appareil directement sur l'appareil, ce qui affecterait tous les spectateurs simultanés et la qualité des enregistrements vidéo historiques enregistrés dans le cloud.

L'exemple suivant montre comment récupérer et mettre à jour la qualité de la diffusion en direct pour un appareil :

• Récupérer les options de qualité compatibles : obtenir les résolutions de streaming disponibles compatibles avec l'appareil. Le code interroge l'attribut supportedQualityHints du trait WebRtcLiveView sur le flux de type d'appareil et expose les qualités compatibles sous la forme d'un StateFlow contenant une liste de valeurs QualityHint (telles que QUALITY_HINT_SD, QUALITY_HINT_HD, QUALITY_HINT_FHD, QUALITY_HINT_QHD ou QUALITY_HINT_UHD).

• Modifier la qualité de la diffusion en direct : appliquez un QualityHint sélectionné pour modifier la résolution de la diffusion en direct active (par exemple, en passant de la définition standard à la haute définition). La fonction changeQuality résout le trait de diffusion en direct de l'appareil et appelle changeLiveViewQuality avec la configuration mediaSessionId active et la configuration QualityHint souhaitée.

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

Activer et désactiver la capacité d'enregistrement

Pour activer la capacité d'enregistrement de la caméra, transmettez TransportStatusEnum.Active à la méthode setTransportStatus() du trait PushAvStreamTransport. Pour désactiver la capacité d'enregistrement, transmettez-lui TransportStatusEnum.Inactive. Dans l'exemple suivant, nous encapsulons ces appels dans un seul appel qui utilise un Boolean pour activer ou désactiver la capacité d'enregistrement :

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

Activer ou désactiver la capacité d'enregistrement de la caméra revient à activer ou désactiver la vidéo de la caméra. Lorsqu'une caméra est activée, elle enregistre (pour les événements et les extraits associés).

Lorsque la capacité d'enregistrement est désactivée (la vidéo de la caméra est désactivée) :

• La caméra peut toujours apparaître comme étant en ligne, conformément à la connectivityState du type d'appareil.
• Le flux en direct n'est pas accessible et la caméra ne détecte aucun événement cloud.

Vérifier si la capacité d'enregistrement est activée

Pour savoir si la capacité d'enregistrement d'une caméra est activée, vérifiez si des connexions sont actives. L'exemple suivant définit deux fonctions pour ce faire :

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

Vous pouvez également utiliser la fonction findTransport() avec un prédicat :

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

Paramètres de la batterie

Vous pouvez contrôler différents paramètres de batterie via les API Home.

Définir la préférence d'utilisation de la batterie

Le paramètre d'équilibre énergétique vous permet de configurer le compromis entre l'autonomie de la batterie et les performances d'un appareil. Vous pouvez créer différents profils de batterie, tels que "Étendue", "Équilibrée" et "Performances", et passer de l'un à l'autre.

Cette fonctionnalité est implémentée en mettant à jour l'attribut currentEnergyBalance du trait EnergyPreference. L'attribut accepte un index entier qui correspond à un profil spécifique défini dans la liste energyBalances de l'appareil (par exemple, 0 pour EXTENDED, 1 pour BALANCED et 2 pour PERFORMANCE).

Une valeur null pour currentEnergyBalance indique que l'appareil utilise un profil personnalisé. Il s'agit d'un état en lecture seule.

Vous trouverez ci-dessous un exemple de structure que l'attribut currentEnergyBalance utilisera, suivi de l'extrait de code réel qui utilise l'attribut.

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

Activer l'économiseur de batterie automatique

Pour configurer cette fonctionnalité, mettez à jour l'attribut currentLowPowerModeSensitivity du trait EnergyPreference. Cet attribut utilise un index pour sélectionner un niveau de sensibilité, où 0 représente généralement Disabled et 1 représente Enabled ou 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) }
}

Obtenir l'état de charge de la batterie

Pour obtenir l'état de charge actuel de l'appareil (en charge, complètement chargé ou non en charge), utilisez l'attribut batChargeState du trait 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"
}

Obtenir le niveau de batterie

Pour obtenir le niveau de batterie actuel, utilisez l'attribut batChargeLevel du trait PowerSource. Le niveau est OK, Warning (faible) ou 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"
}

Obtenir la source d'alimentation

Pour déterminer la source d'alimentation utilisée par l'appareil, utilisez les attributs BatPresent et wiredPresent du trait PowerSource.

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

Paramètres audio

Vous pouvez contrôler différents paramètres audio à l'aide des API Home.

Activer ou désactiver le micro

Pour activer ou désactiver le micro de l'appareil, mettez à jour l'attribut microphoneMuted du trait CameraAvStreamManagement à l'aide de la fonction Kotlin setMicrophoneMuted intégrée :

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

Activer ou désactiver l'enregistrement audio

Pour activer ou désactiver l'enregistrement audio de l'appareil, mettez à jour l'attribut recordingMicrophoneMuted du trait CameraAvStreamManagement à l'aide de la fonction Kotlin setRecordingMicrophoneMuted intégrée :

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

Régler le volume du haut-parleur

Pour ajuster le volume du haut-parleur de l'appareil, mettez à jour l'attribut speakerVolumeLevel du trait CameraAvStreamManagement à l'aide de la fonction Kotlin setSpeakerVolumeLevel intégrée :

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

Paramètres des zones d'activité

Le trait ZoneManagement fournit une interface permettant de gérer les régions d'intérêt personnalisées (zones d'activité) sur les caméras et les sonnettes. Ces zones permettent de filtrer la détection d'événements (comme le mouvement d'une personne ou d'un véhicule) sur des zones spécifiques du champ de vision de l'appareil.

Les zones d'activité sont configurées par l'utilisateur dans une application partenaire. Elles lui permettent de dessiner des zones sur des zones spécifiques du champ de vision de la caméra. Ces zones définies par l'utilisateur sont ensuite traduites dans les structures utilisées par ce trait. Pour en savoir plus sur le fonctionnement des zones d'activité, consultez Configurer et utiliser des zones d'activité.

Les zones d'activité sont généralement définies à l'aide de coordonnées cartésiennes 2D. Le trait fournit TwoDCartesianVertexStruct pour les sommets et TwoDCartesianZoneStruct pour la définition de la zone (nom, sommets, couleur et utilisation).

Vérifier les zones d'activité

Pour afficher les zones d'activité, cochez l'attribut zones du trait 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()
  }

Ajouter une zone d'activité

Pour créer une zone, utilisez la commande createTwoDCartesianZone. Cette commande prend un TwoDCartesianZoneStruct, qui définit le nom, les sommets, la couleur et l'utilisation de la zone.

L'exemple suivant montre comment créer une zone nommée "Porche" avec quatre sommets, de couleur saumon (#F439A0), et utilisée pour la détection de mouvement.

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

Modifier une zone d'activité

Pour mettre à jour une zone existante, utilisez la commande updateTwoDCartesianZone. Cette commande nécessite zoneId et la version mise à jour de TwoDCartesianZoneStruct.

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

Supprimer une zone d'activité

Pour supprimer une zone, utilisez la commande removeZone avec le zoneId spécifique.

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

Déclencheurs d'événements sonores

Le trait AvStreamAnalysis fournit une interface permettant de gérer les déclencheurs de détection d'événements sur les caméras et les sonnettes. Les déclencheurs basés sur la vision (comme les personnes ou les véhicules) peuvent être spécifiques à une zone, tandis que les déclencheurs liés au son sont généralement des configurations au niveau de l'appareil.

Les types de déclencheurs suivants sont disponibles pour la détection des sons avec EventTriggerTypeEnum :

Vérifier l'état de la détection des sons

Pour afficher l'état actuel de la détection du son à l'utilisateur, vous devez vérifier ce que l'appareil prend en charge et ce qui est activé par le matériel de l'appareil. Les deux attributs à vérifier sont les suivants :

• supportedEventTriggers
• enabledEventTriggers

Dans le développement Android à l'aide de Kotlin Flows, vous observerez généralement le trait AvStreamAnalysis à partir de 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)
        )
      }
  }

Mettre à jour l'ensemble des déclencheurs activés

Pour mettre à jour l'ensemble des déclencheurs activés, utilisez la commande SetOrUpdateEventDetectionTriggers, qui accepte une liste de structures 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)
}

Modes d'enregistrement

Le trait RecordingMode fournit une interface permettant de gérer le comportement d'enregistrement vidéo et d'images sur les caméras et les sonnettes. Il permet aux utilisateurs de choisir entre l'enregistrement continu, l'enregistrement en cas d'événement ou la désactivation complète de l'enregistrement (vue en direct uniquement).

RecordingModeEnum définit les stratégies d'enregistrement disponibles :

Vérifier les modes d'enregistrement

Pour afficher la configuration d'enregistrement actuelle, vérifiez les attributs du trait RecordingMode :

• supportedRecordingModes : tous les modes potentiels
• availableRecordingModes : modes sélectionnables
• selectedRecordingMode : mode Actif

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

Changer le mode d'enregistrement

Avant de mettre à jour, assurez-vous que l'index choisi dans l'attribut supportedRecordingModes est présent dans l'attribut availableRecordingModes.

Pour mettre à jour le mode sélectionné, utilisez la fonction setSelectedRecordingMode en transmettant l'index du mode choisi :

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

Autres paramètres

Divers autres paramètres peuvent être contrôlés via les API Home.

Modifier l'orientation de l'image

Vous pouvez faire pivoter l'orientation de l'image (vidéo) de la caméra. La vidéo ne peut être pivotée que de 180 degrés.

Pour modifier l'orientation de l'image de la caméra, mettez à jour l'attribut imageRotation du trait CameraAvStreamManagement à l'aide de la fonction Kotlin setImageRotation intégrée :

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

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

Activer ou désactiver la vision nocturne

Pour activer ou désactiver la vision nocturne de la caméra, utilisez TriStateAutoEnum pour mettre à jour l'attribut nightVision du trait CameraAvStreamManagement à l'aide de la fonction Kotlin setNightVision intégrée :

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

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

Modifier la luminosité du voyant d'état

Pour modifier la luminosité de la LED d'état, utilisez ThreeLevelAutoEnum pour mettre à jour l'attribut statusLightBrightness du trait CameraAvStreamManagement à l'aide de la fonction Kotlin setStatusLightBrightness intégrée :

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

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

Modifier le champ de vision de la caméra

Le champ de vision de la caméra est identique à la fonctionnalité "Zoomer et recadrer" décrite dans l'article d'aide Zoomer et améliorer l'affichage vidéo de la caméra Nest.

Le champ de vision est défini dans un ViewportStruct qui contient quatre valeurs utilisées comme coordonnées du champ de vision. Les coordonnées sont définies comme suit :

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

La détermination des valeurs pour ViewportStruct dépend de l'UI et de l'implémentation de la caméra d'une application. Pour définir le champ de vision de la vidéo de la caméra, mettez à jour l'attribut viewport du trait CameraAvStreamManagement avec un ViewportStruct à l'aide de la fonction Kotlin setViewport intégrée :

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

Activer ou désactiver les données analytiques

Chaque appareil peut choisir individuellement d'envoyer des données analytiques détaillées au cloud Google Home (voir Cloud Monitoring pour les API Home).

Pour activer les données analytiques pour un appareil, définissez la propriété analyticsEnabled de ExtendedGeneralDiagnosticsTrait sur true. Lorsque vous définissez analyticsEnabled, une autre propriété, logUploadEnabled, est automatiquement définie sur true, ce qui permet d'importer les fichiers journaux d'analyse dans le cloud Google Home.

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

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

Configurations de transport et d'enregistrement

Cette section aborde les paramètres liés à la qualité du flux vidéo de la caméra et au déclenchement d'événements. Ces paramètres sont gérés par le trait PushAvStreamTransport.

Lire les paramètres de transport

Cette section explique comment récupérer la configuration actuelle d'une caméra ou d'une sonnette. Il récupère le trait PushAvStreamTransport, trouve la connexion spécifique utilisée pour l'enregistrement, puis extrait les valeurs actuelles de la qualité de la bande passante, de la sensibilité à l'activation et de la durée maximale de l'événement.

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

Modifier les paramètres de transport

Cette section explique comment modifier les paramètres de transport. Il crée un TransportOptionsStruct contenant les nouvelles valeurs, puis utilise la commande modifyPushTransport pour renvoyer ces paramètres mis à jour à l'appareil, en les appliquant à la connexion d'enregistrement trouvée à l'étape précédente.

Pour modifier ces paramètres, utilisez la commande modifyPushTransport avec un 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
    )
}

Déterminer la qualité de la bande passante

La propriété videoStreamId de TransportOptionsStruct correspond à une configuration de flux vidéo spécifique.

Pour obtenir les flux vidéo acceptés, consultez l'attribut allocatedVideoStreams, qui est une liste de VideoStreamStructs. à partir du trait CameraAvStreamManagement de l'appareil.

Ajuster la sensibilité d'activation de l'appareil

La propriété motionSensitivity de TransportTriggerOptionsStruct correspond aux valeurs suivantes :

Ajuster la durée maximale des événements

La propriété maxDuration de TransportMotionTriggerTimeControlStruct correspond aux durées suivantes (en secondes) :

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