# Smart Home SensorState Trait Schema

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

> [!NOTE]
> **Note** : To find other traits with sensing capabilities, you can browse our [smart home traits](https://developers.home.google.com/cloud-to-cloud/traits) documentation. If you cannot find a sensing capability you need, you can [file a
> feature request](https://issuetracker.google.com/issues/new?component=655104&template=1295013) in the public issue tracker.

## Device ATTRIBUTES

Devices with this trait may report the following
attributes as part of the [`SYNC`](https://developers.home.google.com/cloud-to-cloud/intents/sync) operation. To learn
more about handling `SYNC` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/sync).

| 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](https://developers.home.google.com/cloud-to-cloud/traits/sensorstate#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`](https://developers.home.google.com/cloud-to-cloud/intents/query) operation. To learn
more about handling `QUERY` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute).

| 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. |
| `alarmState` | *String* | The alarm state corresponding to the current sensor reading. A pre-alarm or alarm may be triggered when sensor readings approach and reach hazardous levels. Supported values: `IDLE` :   The alarm is idle; detected levels are not hazardous. `PRE_ALARM_1` :   Detected levels are elevated but have not yet reached emergency levels; the levels may soon become hazardous. `PRE_ALARM_2` :   If the device supports multiple alerts before reaching emergency levels, this indicates higher detection levels than PRE_ALARM_1; the levels are continuing to increase and may soon approach emergency levels. `ALARM` :   The detected levels have reached emergency levels and an alarm has been triggered. |
| `alarmSilenceState` | *String* | Indicates silence state for the sensor's alarm, including whether silencing an active alarm is currently allowed. This state may be provided when a pre-alarm or alarm state is active. For a Smoke Detector, the values `ALLOWED` and `DISALLOWED` are not used. The Google Home app has built-in logic to determine if an alarm can be silenced from the app. Supported values: `ALLOWED` :   The alarm is not silenced and silencing the alarm is currently allowed. `DISALLOWED` :   The alarm is not silenced and silencing the alarm is currently not allowed. `SILENCED` :   The alarm has been silenced. |


See [Supported Sensors](https://developers.home.google.com/cloud-to-cloud/traits/sensorstate#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
    }
  ]
}
```

*Sensor device that reports descriptive and numeric state value and indicates an alarm is active.*

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

*Sensor device that reports descriptive and numeric state value and indicates an alarm is silenced.*

```
{
  "currentSensorStateData": [
    {
      "name": "SmokeLevel",
      "currentSensorState": "smoke detected",
      "rawValue": 200,
      "alarmState": "ALARM",
      "alarmSilenceState": "SILENCED"
    }
  ]
}
```

## 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](https://developers.home.google.com/cloud-to-cloud/integration/notifications).

| 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](https://developers.home.google.com/cloud-to-cloud/traits/sensorstate#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](https://developers.home.google.com/cloud-to-cloud/intents/errors-exceptions).