Traits

A trait in the SDM API comprises fields, commands, and events.

Fields

Fields are values with common data types, such as a number or a string. For example, a field might contain a the current mode or the ambient humidity of a Google Nest Thermostat.

Traits and fields can be viewed with a GET call to the desired API endpoint:

GET /enterprises/project-id/devices/device-id
{
  "name" : "enterprises/project-id/devices/device-id",
  "type" : "sdm.devices.types.device-type",
  "traits" : { ... },
  "parentRelations" : [
    {
      "parent" : "enterprises/project-id/structures/structure-id/rooms/room-id",
      "displayName" : "Lobby"
    }
  ]
}

Device types

The sdm.devices.types.device-type returned by the SDM API should not be used to deduce or infer functionality of the actual device it is assigned to. There is no guarantee that a device type will remain stable for a specific device as more features are added to the SDM API. Instead, use the returned traits for the device.

parentRelations

The parentRelations object represents the parent resource of the current resource, either a structure or room. Display name corresponds to the customName field of the Info trait for devices with a structure parent or the RoomInfo trait for devices with a room parent.

Commands

Commands are requests associated with a trait. For example, changing the current mode or temperature setpoint on a Google Nest Thermostat.

A command is sent by an executeCommand API call:

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "command-name",
  "params" : {
    "field" : "value"
  }
}

Most responses to a command are a simple success or failure. See the individual trait guides for specific command usage examples.

Events

Events are asynchronous and managed by Google Cloud Pub/Sub in a single topic per Project ID.

Events are sent by default for any change in the value of a trait field. They can also be sent in response to specific device actions or changes in resource assignments. See Events for more information.

Trait categories

Structure

Traits
Info
sdm.structures.traits.Info
This trait belongs to any structure for structure-related information.
RoomInfo
sdm.structures.traits.RoomInfo
This trait belongs to any room for room-related information.

Device

Traits
Connectivity
sdm.devices.traits.Connectivity
This trait belongs to any device that has connectivity information.
Fan
sdm.devices.traits.Fan
This trait belongs to any device that has the system ability to control the fan.
Humidity
sdm.devices.traits.Humidity
This trait belongs to any device that has a sensor to measure humidity.
Info
sdm.devices.traits.Info
This trait belongs to any device for device-related information.
Settings
sdm.devices.traits.Settings
This trait belongs to any device for device-related settings information.
Temperature
sdm.devices.traits.Temperature
This trait belongs to any device that has a sensor to measure temperature.

Thermostat

Traits
ThermostatEco
sdm.devices.traits.ThermostatEco
This trait belongs to device types of THERMOSTAT that support ECO modes.
ThermostatHvac
sdm.devices.traits.ThermostatHvac
This trait belongs to device types of THERMOSTAT that can report HVAC details.
ThermostatMode
sdm.devices.traits.ThermostatMode
This trait belongs to device types of THERMOSTAT that support different thermostat modes.
ThermostatTemperatureSetpoint
sdm.devices.traits.ThermostatTemperatureSetpoint
This trait belongs to device types of THERMOSTAT that support setting target temperature and temperature range.

Camera

Traits
CameraClipPreview
sdm.devices.traits.CameraClipPreview
This trait belongs to any device that supports the download of a clip preview.
CameraEventImage
sdm.devices.traits.CameraEventImage
This trait belongs to any device that supports generation of images from events.
CameraImage
sdm.devices.traits.CameraImage
This trait belongs to any device that supports taking images.
CameraLiveStream
sdm.devices.traits.CameraLiveStream
This trait belongs to any device that supports live streaming.
CameraMotion
sdm.devices.traits.CameraMotion
This trait belongs to any device that supports motion detection events.
CameraPerson
sdm.devices.traits.CameraPerson
This trait belongs to any device that supports person detection events.
CameraSound
sdm.devices.traits.CameraSound
This trait belongs to any device that supports sound detection events.

Doorbell

Traits
DoorbellChime
sdm.devices.traits.DoorbellChime
This trait belongs to any device that supports a doorbell chime and related press events.