Notice: We're retiring Works with Nest. See the home page for more information.
O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Smoke+CO Alarm

Smoke + CO alarm

Nest Protect is designed to detect smoke and carbon monoxide (CO) in a residential environment, with multiple sensors to help it understand what's happening in the home.

The Nest API provides access to the following data on Nest Protect:

  • Smoke or carbon monoxide (CO) alarm status
  • Battery health state
  • Last manual test status and timestamp
  • Online status and last connection information
  • Structure name and device "where name" (location in the home)

Smoke+CO permissions

For read access to all Smoke+CO alarm API data values, select the Smoke+CO read permission for your client.

There are no write permissions available for the Smoke+CO alarm API.

Smoke+CO identifiers

Device

Nest devices are listed by type as an array of IDs, which can be used to uniquely identify a device via the device path. So a smoke+co alarm ID of "RTMTKxs..." means that you can load the smoke+co alarm device model at devices/smoke_co_alarms/RTMTKxs... via the API.

When a device is connected to multiple products, each developer will see a different ID for that device. For a device that has installed multiple products from the same developer, the developer will see the same ID.

Name

Two name attributes are provided. The shorter name attribute is displayed in user interface labels, while name_long is used in long form text.

name

In this example, name is "Nest Protect".

Name

name_long

In this example, name_long is "Basement Nest Protect".

Name long

Where

where_id

  • A unique, Nest-generated identifier that represents name
  • where_id is read-only, and is created automatically in the call to create a custom where name

Learn more about where names for Nest Thermostats, Nest Protects and Nest Cams.

where_name

When you choose the Smoke+CO read permission, you can access the device where_name from the device object (devices/smoke_co_alarms).

Other metadata

All data values are read only, unless otherwise specified.

Data Value Description
locale The language and country code assigned to this device
software_version A string that represents the firmware currently installed on the device
structure_id A string that uniquely represents this structure; this is the structure that the device is paired with
last_connection The timestamp of the last successful connection to the Nest service
is_online Online status. This is determined by Nest using the last_connection time and an expected reconnection window that is device-specific.

Smoke+CO features

Battery health

Use the battery_health field to view the battery health state.

Value Description
ok Battery level ok
replace Battery level low, should be replaced

CO alarm

Use the co_alarm_state field to view the CO alarm state.

Value Description
ok Normal operation
warning Detection of rising CO levels
emergency CO levels too high, user should exit the home

Smoke alarm

Use the smoke_alarm_state field to view the smoke alarm state.

Value Description
ok Normal operation
warning Detection of rising smoke levels
emergency Smoke levels too high, user should exit the home

Manual test

Use these fields to check if a manual smoke or CO test is currently active, and the last time a successful smoke or CO test was performed.

UI color state

To make it easier to design a coherent cross-product UI, we've provided the ui_color_state field, which gives a high-level indication of the overall state of the Nest Protect. It is derived from is_online, battery_health, co_alarm_state, and smoke_alarm_state, providing an aggregate condition that reflects the actual color indicators displayed in the Nest app.

Error messages

For information on what API call errors mean and how to handle them, see Error Messages.