We want to hear your thoughts on the Google Smart Home platform. Join a user study and receive a gift for your input. Click here to sign up.

Smart Home SensorState Trait Schema

action.devices.traits.SensorState - This trait covers both quantitative measurement (for example, air quality index or smoke level) and qualitative state (for example, whether the air quality is healthy or whether the smoke level is low or high).

Device ATTRIBUTES

Attribute Definition
sensorStatesSupported Array of objects. 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.
  • name: String. This can be any sensor with a descriptive or numeric capability from the Supported Sensors table.
  • descriptiveCapabilities: Object. A description of the sensor's capabilities.
    • availableStates: Array of strings. The available states for the device. The "unknown" state is implicitly supported when the sensor does not return a value.
  • numericCapabilities: Object. Describes the possible numerical values that the sensor can report (for example, indicating that the carbon monoxide level is measured at 200 parts per million).

Supported sensors

Sensor
Descriptive Capabilities
(availableStates)
Numeric Capabilities
(rawValueUnit)
Example device types
AirQuality

fair: The air quality is fair.

good: The air quality is good.

healthy: The air quality is healthy.

moderate: The air quality is moderate.

poor: The air quality is poor.

severe: The air quality is severe.

unhealthy: The air quality is unhealthy.

unhealthy for sensitive groups: The air quality is unhealthy for sensitive groups.

very poor: The air quality is very poor.

very unhealthy: The air quality is very unhealthy.

unknown: The air quality is unknown.

AQI: Reported as an integer from 0 to 500, inclusive.
CarbonDioxideLevel None PARTS_PER_MILLION: Reported with a positive float.
CarbonMonoxideLevel

carbon monoxide detected: The device detects CO.

high: The device detects a large amount of CO.

no carbon monoxide detected: The device detects no CO.

unknown: The CO level is unknown.

PARTS_PER_MILLION: Reported with a positive float.
FilterCleanliness

clean: The filter is clean.

dirty: The filter is dirty.

needs replacement: The filter is very dirty and needs to be replaced.

unknown: The cleanliness of the filter is unknown.

None
FilterLifeTime

good: The filter is good.

new: The filter is new.

replace soon: The filter needs to be replaced soon.

replace now: The filter needs to be replaced now.

unknown: The filter lifetime is unknown.

PERCENTAGE: Reported as a percentage from 0 to 100, inclusive.
HEPAFilterLifeTime None PERCENTAGE: Reported as a percentage from 0 to 100, inclusive.
Max2FilterLifeTime None PERCENTAGE: Reported as a percentage from 0 to 100, inclusive.
PM2.5 None MICROGRAMS_PER_CUBIC_METER: Reported amount of atmospheric particulate matter (PM) that have a diameter of less than 2.5 micrometers.
PM10 None MICROGRAMS_PER_CUBIC_METER: Reported amount of coarse atmospheric particulate matter (PM) that have a diameter of between 2.5 to 10 micrometers.
PreFilterLifeTime None PERCENTAGE: Reported as a percentage from 0 to 100, inclusive.
SmokeLevel

smoke detected: The device detects smoke.

high: The device detects a large amount of smoke.

no smoke detected: The device detects no smoke.

unknown: The smoke level is unknown.

PARTS_PER_MILLION: Reported with a positive float.
WaterLeak

leak: A water leak is detected.

no leak: No water leak is detected.

unknown: The water leakage detection is unknown.

None
RainDetection

rain detected: Rain is detected.

no rain detected: No rain is detected.

unknown: The rain detection is unknown.

None
VolatileOrganicCompounds None PARTS_PER_MILLION: Reported with a positive float.

Example of sensor state with descriptive capability:

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

Example of sensor state with numeric capability:

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

Example of sensor state with descriptive and numeric capability:

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

Sample SYNC Request and Response

Example of sensor state with descriptive capability:
Request
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.SYNC"
    }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onSync((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      agentUserId: '1836.15267389',
      devices: [{
        id: '123',
        type: 'action.devices.types.SENSOR',
        traits: [
          'action.devices.traits.SensorState'
        ],
        name: {
          defaultNames: ['Default sensor name'],
          name: 'Front door',
          nicknames: ['Front door sensor']
        },
        willReportState: true,
        attributes: {
          sensorStatesSupported: [{
            'name': 'AirQuality',
            'descriptiveCapabilities': {
              'availableStates': [
                'healthy',
                'moderate',
                'unhealthy',
                'very unhealthy'
              ]
            }
          }]
        },
        deviceInfo: {
          manufacturer: 'nest',
          model: 'c110',
          hwVersion: '3.2',
          swVersion: '11.4'
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-sensorstate_sync_1.json")
public SyncResponse onSync(@NotNull SyncRequest syncRequest, @Nullable Map<?, ?> headers) {
  Payload payload = new Payload();
  payload.setAgentUserId("1836.15267389");

  payload.setDevices(
      new Device[] {
        new Device.Builder()
            .setId("123")
            .setType("action.devices.types.SENSOR")
            .addTrait("action.devices.traits.SensorState")
            .setName(
                Collections.singletonList("Default sensor name"),
                "Front door",
                Collections.singletonList("Front door sensor"))
            .setWillReportState(true)
            .setAttributes(
                new JSONObject()
                    .put(
                        "sensorStatesSupported",
                        new JSONObject[] {
                          new JSONObject()
                              .put("name", "AirQuality")
                              .put(
                                  "descriptiveCapabilities",
                                  new JSONObject()
                                      .put(
                                          "availableStates",
                                          new String[] {
                                            "healthy", "moderate", "unhealthy", "very unhealthy"
                                          }))
                        }))
            .setDeviceInfo("nest", "c110", "3.2", "11.4")
            .build()
      });

  return new SyncResponse(syncRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.SENSOR",
        "traits": [
          "action.devices.traits.SensorState"
        ],
        "name": {
          "defaultNames": [
            "Default sensor name"
          ],
          "name": "Front door",
          "nicknames": [
            "Front door sensor"
          ]
        },
        "willReportState": true,
        "attributes": {
          "sensorStatesSupported": [
            {
              "name": "AirQuality",
              "descriptiveCapabilities": {
                "availableStates": [
                  "healthy",
                  "moderate",
                  "unhealthy",
                  "very unhealthy"
                ]
              }
            }
          ]
        },
        "deviceInfo": {
          "manufacturer": "nest",
          "model": "c110",
          "hwVersion": "3.2",
          "swVersion": "11.4"
        }
      }
    ]
  }
}
Validator
Example of sensor state with numeric capability:
Request
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.SYNC"
    }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onSync((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      agentUserId: '1836.15267389',
      devices: [{
        id: '123',
        type: 'action.devices.types.SENSOR',
        traits: [
          'action.devices.traits.SensorState'
        ],
        name: {
          defaultNames: ['Default sensor name'],
          name: 'Front door',
          nicknames: ['Front door sensor']
        },
        willReportState: true,
        attributes: {
          sensorStatesSupported: [{
            'name': 'CarbonMonoxideLevel',
            'numericCapabilities': {
              'rawValueUnit': 'PARTS_PER_MILLION'
            }
          }]
        },
        deviceInfo: {
          manufacturer: 'nest',
          model: 'c110',
          hwVersion: '3.2',
          swVersion: '11.4'
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-sensorstate_sync_2.json")
public SyncResponse onSync(@NotNull SyncRequest syncRequest, @Nullable Map<?, ?> headers) {
  Payload payload = new Payload();
  payload.setAgentUserId("1836.15267389");

  payload.setDevices(
      new Device[] {
        new Device.Builder()
            .setId("123")
            .setType("action.devices.types.SENSOR")
            .addTrait("action.devices.traits.SensorState")
            .setName(
                Collections.singletonList("Default sensor name"),
                "Front door",
                Collections.singletonList("Front door sensor"))
            .setWillReportState(true)
            .setAttributes(
                new JSONObject()
                    .put(
                        "sensorStatesSupported",
                        new JSONObject[] {
                          new JSONObject()
                              .put("name", "CarbonMonoxideLevel")
                              .put(
                                  "numericCapabilities",
                                  new JSONObject().put("rawValueUnit", "PARTS_PER_MILLION"))
                        }))
            .setDeviceInfo("nest", "c110", "3.2", "11.4")
            .build()
      });

  return new SyncResponse(syncRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.SENSOR",
        "traits": [
          "action.devices.traits.SensorState"
        ],
        "name": {
          "defaultNames": [
            "Default sensor name"
          ],
          "name": "Front door",
          "nicknames": [
            "Front door sensor"
          ]
        },
        "willReportState": true,
        "attributes": {
          "sensorStatesSupported": [
            {
              "name": "CarbonMonoxideLevel",
              "numericCapabilities": {
                "rawValueUnit": "PARTS_PER_MILLION"
              }
            }
          ]
        },
        "deviceInfo": {
          "manufacturer": "nest",
          "model": "c110",
          "hwVersion": "3.2",
          "swVersion": "11.4"
        }
      }
    ]
  }
}
Validator

Device STATES

State Definition
currentSensorStateData Array of objects.
  • name: String. The sensor name.
  • currentSensorState: String. The current descriptive sensor state. Valid values are listed in the Supported sensors table, under the 'Descriptive Capabilities' column. For example, "healthy" for an air quality sensor.
  • rawValue: Float. The current numeric sensor value.

Sample QUERY Request and Response

User What’s the air quality in the kitchen?
Google Assistant The air quality is healthy.
Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": 'action.devices.QUERY',
    "payload": {
      "devices": [{
        "id": "123",
        "customData": {
          "fooValue": 74,
          "barValue": true,
          "bazValue": "foo"
        }
      }]
    }
  }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onQuery((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      devices: {
        123: {
          on: true,
          online: true,
          currentSensorStateData: [{
                'name': 'AirQuality',
                'currentSensorState': 'healthy'
          }],
          status: 'SUCCESS'
        }
      }
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-sensorstate_query_1.json")
public QueryResponse onQuery(@NotNull QueryRequest queryRequest, @Nullable Map<?, ?> map) {
  QueryResponse.Payload payload = new QueryResponse.Payload();
  payload.setDevices(
      new HashMap<String, Map<String, Object>>() {
        {
          put(
              "123",
              new HashMap<String, Object>() {
                {
                  put("on", true);
                  put("online", true);
                  put(
                      "currentSensorStateData",
                      new ArrayList<Object>() {
                        {
                          add(
                              new HashMap<String, Object>() {
                                {
                                  put("name", "AirQuality");
                                  put("currentSensorState", "healthy");
                                }
                              });
                        }
                      });
                  put("status", "SUCCESS");
                }
              });
        }
      });
  return new QueryResponse(queryRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "on": true,
        "online": true,
        "currentSensorStateData": [
          {
            "name": "AirQuality",
            "currentSensorState": "healthy"
          }
        ],
        "status": "SUCCESS"
      }
    }
  }
}
User What’s the carbon monoxide level in the garage?
Google Assistant The carbon monoxide level is 200 parts per million.
Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": 'action.devices.QUERY',
    "payload": {
      "devices": [{
        "id": "123",
        "customData": {
          "fooValue": 74,
          "barValue": true,
          "bazValue": "foo"
        }
      }]
    }
  }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onQuery((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      devices: {
        123: {
          on: true,
          online: true,
          currentSensorStateData: [{
                'name': 'CarbonMonoxideLevel',
                'rawValue': 200.0
          }],
          status: 'SUCCESS'
        }
      }
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-sensorstate_query_2.json")
public QueryResponse onQuery(@NotNull QueryRequest queryRequest, @Nullable Map<?, ?> map) {
  QueryResponse.Payload payload = new QueryResponse.Payload();
  payload.setDevices(
      new HashMap<String, Map<String, Object>>() {
        {
          put(
              "123",
              new HashMap<String, Object>() {
                {
                  put("on", true);
                  put("online", true);
                  put(
                      "currentSensorStateData",
                      new ArrayList<Object>() {
                        {
                          add(
                              new HashMap<String, Object>() {
                                {
                                  put("name", "CarbonMonoxideLevel");
                                  put("rawValue", 200);
                                }
                              });
                        }
                      });
                  put("status", "SUCCESS");
                }
              });
        }
      });
  return new QueryResponse(queryRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "on": true,
        "online": true,
        "currentSensorStateData": [
          {
            "name": "CarbonMonoxideLevel",
            "rawValue": 200
          }
        ],
        "status": "SUCCESS"
      }
    }
  }
}

Device COMMANDS

None.

Device ERRORS

See the full list of errors and exceptions.