Doorbell device guide for Android

The Doorbell device type is implemented using two traits: PushAvStreamTransport, which handles audio and video stream transport using push-based protocols, and WebRtcLiveView, which provides the ability to control livestreams and talkback.

Always check for attribute and command support for a device prior to using any features or attempting to update attributes. See Control devices on Android for more information.

Start a livestream

To start a livestream, send the Session Description Protocol (SDP) string to the WebRtcLiveView trait's startLiveView() method, which returns a WebRtcLiveViewTrait.StartLiveViewCommand.Response containing three values:

• The SDP for the session.
• The session duration in seconds.
• The session ID, which may be used to extend or terminate the session.

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)

Extend a livestream

Livestreams have a preset duration after which they expire. To lengthen the duration of an active stream, issue an extension request using the WebRtcLiveView.extendLiveView() method:

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

Start and stop talkback

To start talkback, call the WebRtcLiveView trait's startTalkback() method. To stop, use 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)
  }
}

Enable and disable recording capability

To enable the camera's recording capability, pass TransportStatusEnum.Active to the PushAvStreamTransport trait's setTransportStatus() method. To disable the recording capability, pass it TransportStatusEnum.Inactive. In the following example, we wrap these calls in a single call that uses a Boolean to toggle the recording capability:

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

Enabling or disabling the camera's recording capability is the same as turning the camera video on or off. When a camera's video is on, it is recording (for purposes of events and related clips).

When the recording capability is disabled (the camera video is off):

• The camera can still show as online per the connectivityState of the device type.
• The livestream cannot be accessed, nor does the camera detect any cloud events.

Check if recording capability is enabled

To determine if a camera's recording capability is enabled, check to see if any connections are active. The following example defines two functions to do this:

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

Another way to check is using the findTransport() function with a predicate:

// Fetch the current connections
suspend fun queryRecordModeState(cameraDevice: HomeDevice, cameraDeviceType) {
  val pushAvStreamTransport = getPushAvStreamTransport()
  return pushAvStreamTransport.findTransport().let {
      it.transportConfigurations.any { it.transportStatus == TransportStatusEnum.Active
    }
}

Audio settings

Various camera audio settings can be controlled through the Home APIs.

Turn microphone on or off

To turn the device's microphone on or off, update the microphoneMuted attribute of the CameraAvStreamManagement trait using the built-in setMicrophoneMuted Kotlin function:

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

Turn audio recording on or off

To turn audio recording on or off for the device, update the recordingMicrophoneMuted attribute of the CameraAvStreamManagement trait using the built-in setRecordingMicrophoneMuted Kotlin function:

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

Adjust the speaker volume

To adjust the speaker volume for the device, update the speakerVolumeLevel attribute of the CameraAvStreamManagement trait using the built-in setSpeakerVolumeLevel Kotlin function:

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

Other settings

Various other camera settings can be controlled through the Home APIs.

Turn night vision on or off

To turn night vision on or off for the camera, use TriStateAutoEnum to update the nightVision attribute of the CameraAvStreamManagement trait using the built-in setNightVision Kotlin function:

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

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

Change the brightness of the status LED

To change the brightness of the status LED, use ThreeLevelAutoEnum to update the statusLightBrightness attribute of the CameraAvStreamManagement trait using the built-in setStatusLightBrightness Kotlin function:

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

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

Change the camera viewport

The camera viewport is the same as the Zoom and Crop feature described in the Zoom and enhance Nest camera video support article.

The viewport is defined in a ViewportStruct that contains four values, which are used as the coordinates of the viewport. The coordinates are defined as:

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

Determining the values for the ViewportStruct depends on an app's UI and camera implementation. At a very basic level, to set the viewport of the camera video, update the viewport attribute of the CameraAvStreamManagement trait with a ViewportStruct, using the built-in setViewport Kotlin function:

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

Adjust the device wake-up sensitivity

The device's wake-up sensitivity is used to conserve battery by decreasing the range at which the device can sense activity and increasing the time to wake up after detecting that activity.

In the Home APIs, this can be set using the motionSensitivity property of the triggerOptions in the device's transportOptions. These options are defined within the PushAvStreamTransport trait for each device.

The wake-up sensitivity can only be set to the following values:

• 1 = Low
• 5 = Medium
• 10 = High

The process for updating is to find the transport configuration for active recording streams using the findTransport command, then modify the configuration with the new sensitivity value using the modifyPushTransport command:

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

Adjust the maximum event length

The maximum event length is the length of time the camera will record a clip for an event. Through the Home APIs this can be configured, per device, to the same lengths as through the Google Home app (GHA), in intervals of seconds:

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

In the Home APIs, this can be set using the motionTimeControl property of the triggerOptions in the device's transportOptions. These options are defined within the PushAvStreamTransport trait for each device.

The process for updating is to find the transport configuration for active recording streams using the findTransport command, then modify the configuration with the new event length value using the modifyPushTransport command:

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

Chime settings

Various doorbell chime settings can be controlled through the Home APIs.

Change the chime sound

To change the doorbell chime sound, first get the list of chime sounds that are installed the device, using the installedChimeSounds attribute of the Chime trait:

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

Then, update the selectedChime attribute of the Chime trait using the built-in setSelectedChime Kotlin function:

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

Use an external chime

The doorbell can be configured to use an external chime, such as a mechanical bell installed inside the home. This should be configured during doorbell installation to avoid potential damage to the external chime.

To indicate what type of external chime is installed, use ExternalChimeType to update the externalChime attribute of the Chime trait using the built-in setExternalChime Kotlin function:

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

Change the external chime duration

The duration, in seconds, that an external chime rings can be configured through the Home APIs. If the external chime supports a chime duration, a user may want to configure this.

The value set here is dependent on the specifications of the external chime itself, and what its recommended chime duration is.

To change the external chime duration, update the externalChimeDurationSeconds attribute of the Chime trait using the built-in setExternalChimeDurationSeconds Kotlin function:

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