Doorbell (battery)

Nest Doorbell

The Google Nest Doorbell (battery) is supported in the Smart Device Management (SDM) API. This device returns a device type of DOORBELL:

sdm.devices.types.DOORBELL

The Google Nest Doorbell (battery) features a camera, which functions the same as a device type of CAMERA.

Traits

Reference

The following traits, commands, or events are related to this device:

TraitDescriptionCommandsEvents
CameraClipPreviewThis trait belongs to any device that supports the download of a clip preview.ClipPreview
CameraLiveStreamThis trait belongs to any device that supports live streaming.GenerateWebRtcStream
StopWebRtcStream
CameraMotionThis trait belongs to any device that supports motion detection events.Motion
CameraPersonThis trait belongs to any device that supports person detection events.Person
DoorbellChimeThis trait belongs to any device that supports a doorbell chime and related press events.Chime
InfoThis trait belongs to any device for device-related information.

JSON

The absence of a trait in a GET response indicates that the trait or feature is not currently available for the device. See Device types for more information.

{
  "type" : "sdm.devices.types.DOORBELL",
  "traits" : {
    "sdm.devices.traits.CameraClipPreview" : {},
    "sdm.devices.traits.CameraLiveStream" : {
      "maxVideoResolution" : {
        "width" : 640,
        "height" : 480
      },
      "videoCodecs" : ["H264"],
      "audioCodecs" : ["AAC"],
      "supportedProtocols" : ["WEB_RTC"]
    },
    "sdm.devices.traits.CameraMotion" : {},
    "sdm.devices.traits.CameraPerson" : {},
    "sdm.devices.traits.DoorbellChime" : {},
    "sdm.devices.traits.Info" : {
      "customName" : "My device"
    }
  }
}

Handle doorbell and camera events

The following events may be triggered from a DOORBELL device type :

Type Element Description
Event Motion event of the CameraMotion trait Motion has been detected by the camera.
Event Person event of the CameraPerson trait A person has been detected by the camera.
Event Chime event of the DoorbellChime trait The doorbell has been pressed.
For example, here the doorbell button has been pressed:

Payload

{
  "eventId" : "af1f09ce-39c4-4544-a31f-a7d6dda23681",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.DoorbellChime.Chime" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "OzPDbDpRX9rmbjtoY5dS7GFgKT..." } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] } }

A video clip is available for preview and will contain an event with a previewUrl. The clip preview may be published at the same time as the event. Use the eventSessionId to associate this event and the related previewUrl with one or more supported events.

Payload

{
  "eventId" : "814cb09a-2fb0-4a8f-80a7-274ff7cb8104",
  "timestamp" : "2019-01-01T00:00:45Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.DoorbellChime.Chime" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "OzPDbDpRX9rmbjtoY5dS7GFgKT..."
      },
      "sdm.devices.events.CameraClipPreview.ClipPreview" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "previewUrl" : "https://previewUrl/..."
      }
    }
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
    ]
  }
}

A clip preview is a 10 frame video file in mp4 format. You can choose to show the mp4 video file, or transcode it to another format (for example, an animated gif) in order to show a complete 10 frame sequence. The device client capabilities should be considered when selecting a clip preview method.

Access a live stream

The live stream from a camera can be accessed. The following stream formats are supported for this device:

  • WebRTC

For a full list of cameras and supported stream formats, see Supported Devices.

To access a live stream, use the appropriate GenerateFormatStream command of the CameraLiveStream trait.

WebRTC


For a WebRTC stream, send an offerSdp in the GenerateWebRtcStream command of the CameraLiveStream trait to get an answerSdp:

Request

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.CameraLiveStream.GenerateWebRtcStream",
  "params" : {
    "offerSdp" : "offerSdp"
  }
}

Response

{
  "results" : {
    "answerSdp" : "answerSdp",
    "expiresAt" : "2020-01-04T18:30:00.000Z",
    "mediaSessionId" : "0DS1mHd1bjx4LHZRLO3Zavo5PI..."
  }
}

Required: The audio setting in the offerSdp for this command must be set to a=recvonly (receive only).

The answerSdp must be used to generate the live stream within 30 seconds of receiving the response, otherwise it expires. If it expires, execute the GenerateWebRtcStream command again to receive a new answerSdp.

When opening WebRTC channels for the live stream, make sure to create a data channel as well as a video channel.

Extend a live stream

Camera live stream sessions are only valid for 5 minutes. If you need to extend the lifetime of a live stream, use the appropriate ExtendFormatStream command of the CameraLiveStream trait for the stream format you generated.

WebRTC


Stop a live stream

Any time you are no longer using a camera live stream, you should stop it and invalidate the stream. To do so, use the appropriate StopFormatStream command of the CameraLiveStream trait for the stream format you generated.

WebRTC


To stop a WebRTC stream, specify the media session ID with the StopWebRtcStream command of the CameraLiveStream trait:

Request

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.CameraLiveStream.StopWebRtcStream",
  "params" : {
    "mediaSessionId" : "0DS1mHd1bjx4LHZRLO3Zavo5PI..."
  }
}

Response

{}

Errors

The following error code(s) may be returned in relation to this device:

Error Message RPC Troubleshooting
Command is not supported for doorbell. FAILED_PRECONDITION A WebRTC stream cannot be extended on battery-powered doorbells. If a stream on a doorbell needs to be viewed beyond the initial session length, stop the existing stream and generate a new one.

See the API Error Code Reference for the full list of API error codes.