Smart Home SensorState Trait Schema

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

Note: To find other traits with sensing capabilities, you can browse our smart home traits documentation. If you cannot find a sensing capability you need, you can file a feature request in the public issue tracker.

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

Devices 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.