Guide des sonnettes pour Android

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

Vérifiez toujours si un appareil est compatible avec les attributs et les commandes avant d'utiliser des fonctionnalités ou de tenter de mettre à jour des attributs. Pour en savoir plus, consultez Contrôler les appareils surAndroid.

Lancer une diffusion 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 la terminer.

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)

Prolonger une diffusion en direct

Les diffusions en direct ont une durée prédéfinie au terme de laquelle elles expirent. Pour prolonger la durée d'un flux actif, envoyez une demande de prolongation à l'aide de 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 TalkBack

Pour démarrer TalkBack, 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)
  }
}

Activer et désactiver la fonctionnalité d'enregistrement

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

// Start or stop recording for all connections.
suspend fun setCameraRecording(isOn: Boolean) {
  val pushAvStreamTransport = getPushAvStreamTransport
  if(isOn) {
    pushAvStreamTransport.setTransportStatus(TransportStatusEnum.Active)
  } else {
    pushAvStreamTransport.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. Lorsque la vidéo d'une caméra est activée, elle enregistre (pour les événements et les extraits associés).

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

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

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

Pour savoir si la fonctionnalité 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(cameraDevice: HomeDevice, cameraDeviceType) {
  // Query the device for pushAvStreamTransport
  val pushAvTrait = getPushAvStreamTransport()
  return pushAvTrait.recordModeActive()
}

// 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(cameraDevice: HomeDevice, cameraDeviceType) {
  val pushAvStreamTransport = getPushAvStreamTransport()
  return pushAvStreamTransport.findTransport().let {
      it.transportConfigurations.any { it.transportStatus == TransportStatusEnum.Active
    }
}

Paramètres audio

Différents paramètres audio de la caméra peuvent être contrôlés via les 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 sur 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()) }
}

Autres paramètres

Vous pouvez contrôler d'autres paramètres de la caméra à l'aide des API Home.

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 intégrée setNightVision :

// 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 la fenêtre d'affichage 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'assistance Zoomer et améliorer l'affichage vidéo de la caméra Nest.

La fenêtre d'affichage est définie dans un ViewportStruct qui contient quatre valeurs utilisées comme coordonnées de la fenêtre d'affichage. 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 l'appareil photo d'une application. Pour définir le viewport 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(),
    )
) }

Ajuster la sensibilité d'activation de l'appareil

La sensibilité au réveil de l'appareil permet d'économiser la batterie en réduisant la plage à laquelle l'appareil peut détecter une activité et en augmentant le temps de réveil après la détection de cette activité.

Dans les API Home, cette propriété peut être définie à l'aide de la propriété motionSensitivity de triggerOptions dans transportOptions de l'appareil. Ces options sont définies dans le trait PushAvStreamTransport pour chaque appareil.

La sensibilité à la sortie de veille ne peut être définie que sur les valeurs suivantes :

• 1 = Faible
• 5 = Moyen
• 10 = Élevé

Pour mettre à jour la configuration, vous devez trouver la configuration du transport pour les flux d'enregistrement actifs à l'aide de la commande findTransport, puis modifier la configuration avec la nouvelle valeur de sensibilité à l'aide de la commande modifyPushTransport :

// Create a struct with the new wake-up sensitivity
val toUpdate =  TransportOptionsStruct(
  triggerOptions =
    TransportTriggerOptionsStruct(
      motionSensitivity =
        OptionalValue.present(wakeUpSensitivity.toUByte())
    )
  )

// Get the configurations for active connections
val connections  = pushAvStreamTransport.findTransport().transportConfigurations
  // Update all recording streams with the new transport options.
  for (connection in connections) {
    if (connection.transportOptions.getOrNull()?.streamUsage == StreamUsageEnum.Recording) {
      trait.modifyPushTransport(
        connectionId = connection.connectionId,
        transportOptions = toUpdate,
      )
    }
  }

Ajuster la durée maximale des événements

La durée maximale des événements correspond à la durée d'enregistrement vidéo d'un événement par la caméra. Grâce aux API Home, vous pouvez configurer cette durée pour chaque appareil, avec les mêmes valeurs que dans Google Home app (GHA), par intervalles de secondes :

• 10 secondes
• 15 secondes
• 30 secondes
• 60 secondes (1 minute)
• 120 secondes (2 minutes)
• 180 secondes (3 minutes)

Dans les API Home, cette propriété peut être définie à l'aide de la propriété motionTimeControl de triggerOptions dans transportOptions de l'appareil. Ces options sont définies dans le trait PushAvStreamTransport pour chaque appareil.

Pour mettre à jour la configuration du transport, vous devez d'abord trouver la configuration du transport pour les flux d'enregistrement actifs à l'aide de la commande findTransport, puis modifier la configuration avec la nouvelle valeur de durée de l'événement à l'aide de la commande modifyPushTransport :

// Create a struct with the new max event length
// where maxDuration is the length in seconds
val toUpdate =  TransportOptionsStruct(
  triggerOptions =
    TransportTriggerOptionsStruct(
      motionTimeControl =
        OptionalValue.present(
          TransportMotionTriggerTimeControlStruct(maxDuration = it.toUInt())
        )
    )
  )

// Get the configurations for active connections
val connections  = pushAvStreamTransport.findTransport().transportConfigurations
  // Update all recording streams with the new transport options.
  for (connection in connections) {
    if (connection.transportOptions.getOrNull()?.streamUsage == StreamUsageEnum.Recording) {
      trait.modifyPushTransport(
        connectionId = connection.connectionId,
        transportOptions = toUpdate,
      )
    }
  }

Paramètres du carillon

Vous pouvez contrôler différents paramètres du carillon de la sonnette via les API Home.

Modifier le son du carillon

Pour modifier le son de la sonnerie, commencez par obtenir la liste des sons de sonnerie installés sur l'appareil à l'aide de l'attribut installedChimeSounds du trait Chime :

// Get a list of chimes and identify the currently selected one
private val doorbellChimeTraitFlow: Flow =
    device.traitFromType(Chime, GoogleDoorbellDevice)
val chimeSounds = doorbellChimeTraitFlow.first().installedChimeSounds ?: emptyList()

Ensuite, mettez à jour l'attribut selectedChime du trait Chime à l'aide de la fonction Kotlin setSelectedChime intégrée :

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

Utiliser un carillon externe

La sonnette peut être configurée pour utiliser un carillon externe, comme une cloche mécanique installée à l'intérieur de la maison. Ce paramètre doit être configuré lors de l'installation de la sonnette pour éviter d'endommager le carillon externe.

Pour indiquer le type de carillon externe installé, utilisez ExternalChimeType pour mettre à jour l'attribut externalChime du trait Chime à l'aide de la fonction Kotlin setExternalChime intégrée :

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

Modifier la durée du carillon externe

La durée, en secondes, pendant laquelle une sonnerie externe sonne peut être configurée à l'aide des API Home. Si le carillon externe prend en charge une durée de sonnerie, l'utilisateur peut souhaiter la configurer.

La valeur définie ici dépend des spécifications du carillon externe lui-même et de la durée recommandée du carillon.

Pour modifier la durée du carillon externe, mettez à jour l'attribut externalChimeDurationSeconds du trait Chime à l'aide de la fonction Kotlin setExternalChimeDurationSeconds intégrée :

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