Doorbell (legacy)

All legacy Nest Doorbells are supported in the Smart Device Management (SDM) API. This device returns a device type of DOORBELL:

sdm.devices.types.DOORBELL

The Google Nest Doorbell (legacy) 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:

Trait	Description	Commands	Events
CameraEventImage	This trait belongs to any device that supports generation of images from events.	GenerateImage
CameraImage	This trait belongs to any device that supports taking images.
CameraLiveStream	This trait belongs to any device that supports live streaming.	GenerateRtspStream ExtendRtspStream StopRtspStream
CameraMotion	This trait belongs to any device that supports motion detection events.		Motion
CameraPerson	This trait belongs to any device that supports person detection events.		Person
CameraSound	This trait belongs to any device that supports sound detection events.		Sound
DoorbellChime	This trait belongs to any device that supports a doorbell chime and related press events.		Chime
Info	This 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.CameraEventImage" : {},
    "sdm.devices.traits.CameraImage" : {
      "maxImageResolution" : {
        "width" : 1280,
        "height" : 960
      }
    },
    "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.CameraSound" : {},
    "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	Sound event of the CameraSound trait	Sound 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" : "fec605ab-bd45-44ae-baf7-7acfcf1732c5",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.DoorbellChime.Chime" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "QZooRp6RSdVnMNFVMLerALDMKL..."
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

The payload of this event contains an eventId that can be used with the GenerateImage command. This command returns a download URL for the camera image related to the event:

Request

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.CameraEventImage.GenerateImage",
  "params" : {
    "eventId" : "TA0nrQhEbyMoTEzYDHixCiEWe_..."
  }
}

Response

{
  "results" : {
    "url" : "https://domain/sdm_event_snapshot/dGNUlTU2CjY5Y3VKaTZwR3o4Y1...",
    "token" : "g.0.eventToken"
  }
}

Download a camera image

Make a GET call to the url from a GenerateImage command response, using the token in the HTTP Authorization header with Basic authorization, to download the camera image:

curl -H "Authorization: Basic g.0.eventToken" \
      https://domain/sdm_event_snapshot/dGNUlTU2CjY5Y3VKaTZwR3o4Y1...

Use width or height query parameters to customize the resolution of the downloaded image. Only one of these parameters need to specified. The other parameter is scaled automatically according to the camera's aspect ratio.

For example, if the camera's aspect ratio is 4:3, to download the camera image with a resolution of 480 x 360 specify either the width or the height:

Width

curl -H "Authorization: Basic g.0.eventToken" \
      https://domain/sdm_event_snapshot/dGNUlTU2CjY5Y3VKaTZwR3o4Y1...?width=480

Height

curl -H "Authorization: Basic g.0.eventToken" \
      https://domain/sdm_event_snapshot/dGNUlTU2CjY5Y3VKaTZwR3o4Y1...?height=360

Other restrictions to the download URL apply:

If both parameters are provided in the URL, width is used and height is ignored.
If neither parameter is provided in the URL, a default value of 480 is chosen for the width.

See the CameraImage trait for information on image properties.

Access a live stream

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

RTSP

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.

RTSP

For an RTSP stream, the GenerateRtspStream command of the CameraLiveStream trait command returns the stream URL and related streamToken:

Request

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

Response

{
  "results" : {
    "streamUrls" : {
      "rtspUrl" : "rtsps://someurl.com/CjY5Y3VKaTZwR3o4Y19YbTVfMF...?auth=g.0.streamingToken"
    },
    "streamExtensionToken" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
    "streamToken" : "g.0.streamingToken",
    "expiresAt" : "2018-01-04T18:30:00.000Z"
  }
}

Then use the stream URL to access the camera live stream:

rtsps://someurl.com/CjY5Y3VKaTZwR3o4Y19YbTVfMF...?auth=g.0.streamingToken

RTSP live stream URLs cannot be shared between clients. A stream URL can only be used by one client at a time. If multiple clients want to stream from the same camera at the same time, RTSP commands must be sent for each individual client, and each individual client must use its own stream URL.

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.

RTSP

To extend an RTSP stream, use the ExtendRtspStream command of the CameraLiveStream trait command to get new streamExtensionToken and streamToken values:

Request

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

Response

{
  "results" : {
    "streamExtensionToken" : "dGNUlTU2CjY5Y3VKaTZwR3o4Y1...",
    "streamToken" : "g.0.newStreamingToken",
    "expiresAt" : "2018-01-04T18:30:00.000Z"
  }
}

Update the stream URL with these new values to continue viewing the live stream:

rtsps://someurl.com/dGNUlTU2CjY5Y3VKaTZwR3o4Y1...?auth=g.0.newStreamingToken

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.

RTSP

To stop an RTSP stream, use the token to invalidate with the StopRtspStream command of the CameraLiveStream trait command:

Request

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

Response

{}

Errors

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

Error Message	RPC	Troubleshooting
Camera image is no longer available for download.	`DEADLINE_EXCEEDED`	Event images expire 30 seconds after the event is published. Make sure to download the image prior to expiration.
Event id does not belong to the camera.	`FAILED_PRECONDITION`	Use the correct `eventID` returned by the camera event.

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