Display

Nest Hub Max

The Google Nest Hub Max display is supported in the Smart Device Management (SDM) API. This device returns a device type of DISPLAY:

sdm.devices.types.DISPLAY

The Google Nest Hub Max features a camera, which functions the same as a device type of CAMERA.

Traits

Reference

The following trait(s) 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
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.DISPLAY",
  "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"],
    },
    "sdm.devices.traits.CameraMotion" : {},
    "sdm.devices.traits.CameraPerson" : {},
    "sdm.devices.traits.CameraSound" : {},
    "sdm.devices.traits.Info" : {
      "customName" : "My device"
    }
  }
}

Handle camera events

The following events may be triggered from a DISPLAY device type:
  • Motion — Motion has been detected by the camera.
  • Person — A person has been detected by the camera.
  • Sound — Sound has been detected by the camera.
For example, here the camera has detected motion:

Payload

{
  "eventId" : "2c1ee365-b555-40f7-880f-3f94d81ee018",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "AXpuQ-Dv8zei13SIiJF95nCBYu...",
      }
    }
  "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" : "eKO5WCaPx44b7yFjlWnDXejKAX..."
  }
}

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:

  • RTSP

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

For example, for an RTSP stream, the GenerateRtspStream 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"
  }
}

Use the stream URL to access the camera live stream:

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

Extend a live stream

Access tokens for camera live streams 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.

For example, to extend an RTSP stream, use the ExtendRtspStream 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 token for that stream. To do so, use the appropriate StopFormatStream command of the CameraLiveStream trait for the stream format you generated.

For example, to stop an RTSP stream, use the token to invalidate with the StopRtspStream 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 Device Access error codes.