Smart Home SensorState Trait Schema

action.devices.traits.SensorState - This trait covers both quantitative measurement and qualitative state.

Device ATTRIBUTES

Devices with this trait may report the following attributes as part of the SYNC operation. To learn more about handling SYNC intents, see Intent fulfillment.

Attributes Type Description
sensorStatesSupported Array

Required.

Each object represents sensor state capabilities supported by this specific device. Each sensor must have at least a descriptive or numeric capability. Sensors can also report both, in which case the numeric value will be preferred.

[item, ...] Object

Supported sensor capabilities.

Requires at least 1 item.

name String

Required.

Supported sensor type. See the Supported Sensors table.

descriptiveCapabilities Object

A description of the sensor's capabilities.

availableStates Array

Required.

List of the available states for the device. The "unknown" state is implicitly supported when the sensor does not return a value.

[item, ...] String

Supported descriptive state value.

Requires at least 1 item.

numericCapabilities Object

Describes the possible numerical values that the sensor can report.

rawValueUnit String

Required.

Supported numerical unit.

See Supported Sensors for more details on the different capabilities and sensor types this trait supports.

Examples

Sensor device that reports descriptive state value.

{
  "sensorStatesSupported": [
    {
      "name": "AirQuality",
      "descriptiveCapabilities": {
        "availableStates": [
          "healthy",
          "moderate",
          "unhealthy",
          "very unhealthy"
        ]
      }
    }
  ]
}

Sensor device that reports numeric state value.

{
  "sensorStatesSupported": [
    {
      "name": "CarbonMonoxideLevel",
      "numericCapabilities": {
        "rawValueUnit": "PARTS_PER_MILLION"
      }
    }
  ]
}

Sensor device that reports descriptive and numeric state value.

{
  "sensorStatesSupported": [
    {
      "name": "SmokeLevel",
      "numericCapabilities": {
        "rawValueUnit": "PARTS_PER_MILLION"
      },
      "descriptiveCapabilities": {
        "availableStates": [
          "smoke detected",
          "high",
          "no smoke detected"
        ]
      }
    }
  ]
}

Supported Sensors

The following tables list the supported sensor types and their associated capabilities.

Air quality

Name Descriptive Capabilities Numeric Capabilities

Supported values:

AirQuality

Supported values:

healthy
moderate
unhealthy
unhealthy for sensitive groups
very unhealthy
hazardous
good
fair
poor
very poor
severe
unknown

Supported values:

AQI

Carbon monoxide

Name Descriptive Capabilities Numeric Capabilities

Supported values:

CarbonMonoxideLevel

Supported values:

carbon monoxide detected
high
no carbon monoxide detected
unknown

Supported values:

PARTS_PER_MILLION

Smoke level

Name Descriptive Capabilities Numeric Capabilities

Supported values:

SmokeLevel

Supported values:

smoke detected
high
no smoke detected
unknown

Supported values:

PARTS_PER_MILLION

Filter cleanliness

Name Descriptive Capabilities Numeric Capabilities

Supported values:

FilterCleanliness

Supported values:

clean
dirty
needs replacement
unknown
Not supported.

Water leak

Name Descriptive Capabilities Numeric Capabilities

Supported values:

WaterLeak

Supported values:

leak
no leak
unknown
Not supported.

Rain detection

Name Descriptive Capabilities Numeric Capabilities

Supported values:

RainDetection

Supported values:

rain detected
no rain detected
unknown
Not supported.

Filter lifetime

Name Descriptive Capabilities Numeric Capabilities

Supported values:

FilterLifeTime

Supported values:

new
good
replace soon
replace now
unknown

Supported values:

PERCENTAGE

Computed filter lifetime

Name Descriptive Capabilities Numeric Capabilities

Supported values:

PreFilterLifeTime
HEPAFilterLifeTime
Max2FilterLifeTime
Not supported.

Supported values:

PERCENTAGE

Carbon dioxide level

Name Descriptive Capabilities Numeric Capabilities

Supported values:

CarbonDioxideLevel
Not supported.

Supported values:

PARTS_PER_MILLION

Particulate matter

Name Descriptive Capabilities Numeric Capabilities

Supported values:

PM2.5
PM10
Not supported.

Supported values:

MICROGRAMS_PER_CUBIC_METER

Volatile organic compounds

Name Descriptive Capabilities Numeric Capabilities

Supported values:

VolatileOrganicCompounds
Not supported.

Supported values:

PARTS_PER_MILLION

Device STATES

Entities with this trait may report the following states as part of the QUERY operation. To learn more about handling QUERY intents, see Intent fulfillment.

States Type Description
currentSensorStateData Array

Required.

List of current sensor states.

[item, ...] Object

Current sensor state.

name String

Required.

Sensor state name. Matches a value from sensorStatesSupported.

currentSensorState String

Current descriptive state value. Matches a value from sensorStatesSupported.

rawValue Number

Current numeric sensor value.

See Supported Sensors for more details on the different capabilities and sensor types this trait supports.

Examples

Sensor device that reports descriptive state value.

{
  "currentSensorStateData": [
    {
      "name": "AirQuality",
      "currentSensorState": "healthy"
    }
  ]
}

Sensor device that reports numeric state value.

{
  "currentSensorStateData": [
    {
      "name": "CarbonMonoxideLevel",
      "rawValue": 200
    }
  ]
}

Sensor device that reports descriptive and numeric state value.

{
  "currentSensorStateData": [
    {
      "name": "SmokeLevel",
      "currentSensorState": "smoke detected",
      "rawValue": 200
    }
  ]
}

Device COMMANDS

None.

Device NOTIFICATIONS

Devices with this trait may return the following notification payload as part of a device state change. To learn more about implementing notifications, see Notifications for smart home Actions.

Fields Type Description
SensorState Object

Required.

Notification payload.

priority Integer

Required.

Represents the notification level. The currently supported value is 0, which indicates that the notification should be spoken aloud.

name String

Required.

Sensor state name. See list of supported sensor types for notifications.

currentSensorState String

Required.

Current descriptive state value. See list of supported sensor types for notifications.

The notification payload can contain the following sensor types:

  • AirQuality
  • CarbonMonoxideLevel
  • SmokeLevel
  • FilterCleanliness
  • WaterLeak
  • RainDetection
  • FilterLifeTime

See Supported Sensors for more details on the different capabilities supported by each sensor type.

Examples

The detects smoke.

{
  "SensorState": {
    "priority": 0,
    "name": "SmokeLevel",
    "currentSensorState": "high"
  }
}

Device ERRORS

See the full list of errors and exceptions.